API Key、请求头、JSON 与流式返回

建议用时：25 分钟（含练习）

学习目标

能够读懂不含真实凭证的 curl 示例，并说明认证头、JSON 请求体和流式响应。

本节产出

一份脱敏请求标注稿

核心知识：认证、内容和传输方式各管一件事

一个模型请求经常同时涉及 API Key、HTTP 请求头、JSON 和流式响应。把它们混在一起，会让排错变得困难。API Key 是凭证；请求头传递认证方式与内容类型等元信息；JSON 是一种数据表示格式；流式响应则让客户端在完整结果生成前逐步收到事件或内容片段。任何一个部分正确，都不能保证其余部分正确。

不少服务使用 Authorization: Bearer ... 认证，也有服务采用专门的密钥头或其他认证机制。只能按对应文档配置，不应把一种写法视为所有厂商的标准。密钥通常代表某个账号或项目的访问能力，应从受保护的服务端配置中读取，避免出现在公开网页代码、URL 查询参数和共享截图中。

JSON 用键值表达结构。字符串需要双引号，布尔值 true 不等于字符串 "true"，对象末尾通常不能有多余逗号。更重要的是字段语义：一个服务可能接受 messages，另一个使用 input。JSON 能被解析，只说明语法有效；字段名称、类型和组合仍须符合接口合同。

{
  "model": "example-model-id",
  "input": "请用一句话概括这段虚构材料。",
  "stream": true
}

这是一份阅读用示意对象，不保证能直接发送给任何实际服务。复制示例前，必须核对目标接口接受哪些字段。练习只需要理解结构，不要求使用真实密钥或产生收费请求。

流式输出不是每次只发送一个字

流式服务常逐步发送事件，客户端解析后把可展示的部分追加到界面。一个事件可能含若干字符、空片段、状态信息、工具调用参数或其他结构，具体依接口而定。网络收到的一块字节也不一定刚好对应一个事件：

一个事件

一个事件可能被拆成多块。

一块字节

多条事件也可能在同一块里到达。

图中把“解析事件”放在“展示文本”之前，就是为了避免把底层字节块直接当成完整 JSON。若服务使用 Server-Sent Events，事件之间有协议规定的分隔方式；模型服务还会定义自己的事件类型和结束约定，不能对所有服务硬编码同一个结束字符串。

看到文字，不代表请求正常结束

假设界面已经显示了前三段内容，连接随后断开。它可能只是网络中断，也可能上游明确返回了错误。客户端不应因为“有内容”就把结果标为完成。应区分进行中、正常结束、部分结果、失败和取消等状态，并保留适当的重试或继续方式。

用户点击取消后，浏览器停止显示不一定意味着上游立即停止处理或计费，具体取决于整个调用链。课程中不能承诺“关闭窗口就不会花钱”。正确工程做法是按服务支持的取消机制处理，并用实际用量记录验证成本行为。

案例：为什么流式内容变成一串报错

一个教学客户端对每一块网络数据都执行 JSON.parse()。第一块只有 {"type":"text，第二块才包含后半段。于是客户端报告“JSON 格式错误”，但服务发送的完整事件其实没有问题。

应使用与协议匹配的流解析器：先缓冲字节、正确解码文本，再识别完整事件，最后解析事件数据。不能简单按每次读取分割，也不能假设换行总是一次收到。对于 UTF-8 文本，多字节字符也可能跨字节块，需要使用支持连续解码的方式。

另一个错误是把整个响应当作普通 JSON 一次解析，即使响应类型实际上是事件流。排错时先看响应的 Content-Type 与接口文档，再决定采用非流式解析还是事件处理。不要为了解决解析问题把服务端密钥贴到在线“请求测试”网站。

动手练习

1. 将一个示意请求分成认证头、内容类型、JSON 请求体三个部分，指出哪部分含敏感信息，哪部分可以分享给同伴排错。
2. 假设一个事件字符串被拆成三段，手工把它们拼回完整事件，说明为什么每段都单独解析会失败。
3. 为客户端画出“等待、接收中、完成、部分失败、取消”的状态图，写出每个状态给用户看的提示。

参考答案与推演

展开

完成检查

• 能区分凭证、请求头、JSON 字段和流式协议。
• 知道字节块、事件和 Token 并非一一对应。
• 不把部分输出当作完整成功，能解释异常与取消的区别。
• 示例与日志中没有真实密钥，解析方式依据真实接口合同。

参考与来源

• MDN：Using server-sent events：了解事件流格式和客户端处理。
• OpenAI：Streaming API responses：查看一个模型服务如何定义流式事件。