「跑通了」是学习大模型 API 最容易达到、也最容易误导人的里程碑。一条 curl 返回 200，终端打印出一段回答，很多人到这里就认为学会了。可一旦换场景——要流式、要结构化、要控成本、要排障——同一套代码立刻不够用，因为跑通只验证了链路，没验证判断。

这一节把「学会」拆成三个阶段，每个阶段给一条可检验的验收标准。

一、问题不是「学多久」，而是「学到什么程度算够」

技术书的「学完」有两种含义：读完了，和能用了。前者按页数计，后者按能力计。对工程岗来说，只有第二种有意义。

按能力分，Grok API 的学习有三道门槛：

• 能跑通：发出请求、正确取到答案、看懂报错。
• 能算清：估算成本、找到主要杠杆、守住预算。
• 能上线：处理流式中断、结构化输出、工具调用与检索，并能交接。

三道门槛对应不同的章节，也对应不同的验收方式。跳过任何一道，后面都会以「线上事故」的形式补课。

二、三个阶段与验收标准

阶段	对应章节	验收标准
能跑通	1–3	用 input 发出请求、用 output_text 取答案，并能解释 401/404/429 的差别
能算清	4–5	能估算月度成本，说出「缓存与长尾请求」为何排在第一
能上线	6–10	流式可中断可重连、结构化输出可校验、失败可定位、能写交接清单

三件要强调的事：

• 「能跑通」的标准不是返回 200。是你能说清请求发到了哪、答案从哪个字段取、失败时先查哪一层。只验证 200，等于只验证了网络。
• 「能算清」的核心是分账。文本按 token、图像按张、视频按秒、语音按分钟；文本内部还分两档。能把这些分开算，才算会估成本。
• 「能上线」的标志是能排障。不是「没出过错」，而是「出错时能在十分钟内定位到层」。这一条对应第 6 章的三类中断和第 10 章的重试策略。

三、前置知识与不要求

需要：

• 能读写 Python 或 JavaScript，看得懂异步与迭代器。
• 理解 HTTP 与 JSON：状态码、请求头、响应体。
• 会用环境变量管理密钥，不把密钥写进源码。

不要求：

• 不需要 GPU，也不需要本地部署模型。
• 不需要真实付费额度——本书代码全部用 mock 与静态校验，可离线运行。
• 不需要先学完官方文档。本书按决策链组织，遇到具体事实会给出处与核验日期。

四、四个最常见的起步误区

误区	表现	后果
只记 base_url	以为改一行地址就完成接入	字段代际不匹配，取到空值
不看接口代际	照抄 messages 写法	解析层与调用层错位
只按平均 token 估成本	用请求数乘单价	漏掉长尾请求与跳档
把流式当普通请求	一次性读完整响应	首 token 慢、中断无法处理

四个误区的共同点，是把「能返回」当成「已掌握」。本书的每一节判据卡，本质上都在防这一类误判。

五、预期输出与异常分支

这一节的产出是一张自评表。读完应能给自己打三个勾：

阶段	自检问题	能答上来
能跑通	请求发到哪、答案从哪取、401 先查什么	三个都能立刻答
能算清	我的场景有几条计费线、最大杠杆是什么	能列出并排序
能上线	流断了怎么办、工具返回不合 schema 怎么办	有明确处置

如果某一栏答不上来，对应的章节就是你的下一站；不必从第 1 章重读。

六、判据卡

判断项	该这么做	不该这么做
判断「学会」	用「能否排障」验收	以「跑通一次」为准
学习顺序	跑通 → 算清 → 上线	直接跳到流式与工具
成本认知	按能力域分账	只记一个总价
前置准备	环境变量 + mock 即可开练	等充值后再开始
遇阻时	回到对应章节的异常表	从头重读全书

这张卡的重点是用能力验收，不用页数验收。五个判断项都在把「学完」从阅读行为拉回工程能力。

七、来源与核验

• 官方 Quickstart：https://docs.x.ai/developers/quickstart（核验日期 2026-11-04）。responses.create、input、output_text 与 base_url 写法以该页为准。
• 官方定价页：https://docs.x.ai/developers/pricing（核验日期 2026-11-04）。分档计价与缓存价的单位以该页为准；本节不给具体数值。
• 三阶段划分与验收标准为本书自定，用于自评，不代表官方认证体系。

八、动手试

1. 就「能跑通」阶段给自己出一道题：写出请求地址、入参字段、取答案字段、401 的第一排查动作。四个都写对才算过。
2. 列出你项目会碰到的计费线，按「影响最大」排序。排序依据写出来，而不是只写结论。
3. 给自己定一条「能上线」的验收线：例如「流式中断后能在 10 分钟内定位到是缓冲、截断还是连接问题」。把它写进项目文档，作为上线前必须过的检查项。