Claude API 流式传输——关键特性详解
Claude API 流式传输的工作原理——SSE 事件、后端代理配置、TTFT 与成本控制、断流恢复以及生产环境可靠性建议。
如果你想让 Claude 显得快，就打开流式传输。 与其等待 15–25 秒 才拿到一条完整回复，用户往往能在约 300–800 ms 内看到第一个 token。
简短版本如下：
- 当我希望回复边生成边显示时，我会用 SSE 流式传输
- 我会把 Claude 调用放在后端代理之后，以保护 API 密钥
- 我会关注 TTFT（首个 token 到达时间）、
max_tokens和断连，以控制体验与开销 - 我会按顺序解析流式事件：
message_start、内容块事件、message_delta，最后是message_stop - 我会缓冲工具 JSON 片段，直到内容块结束
- 我会为断连做好预案，因为 Claude 原生不支持恢复流
有几个数字值得关注：
- Haiku 4.5： TTFT 约 410 ms
- Sonnet 4.6： TTFT 约 720 ms
- Opus 4.7： TTFT 约 980 ms
- 默认代理超时 30–60 秒 可能会截断较长的输出
- 通常需要更长的读取超时，约 120–300 秒
- 批处理任务的成本可能比标准 token 费率低 50%
说白了：流式传输改变的是_传递方式_，而非模型本身。Claude API 通过一条实时连接以小的事件块发送文本，我的应用则在屏幕上重建出最终答案。对于聊天、副驾驶和助手类应用，这通常意味着更好的用户感受、更少的空闲超时问题，以及在客户端和后端两侧做更多的工作。
以下是最重要的几点：
| 领域 | 我会重点关注的内容 |
|---|---|
| 速度 | 首个 token 时间、提示词大小、模型选择 |
| 配置 | stream: true、SSE 处理、关闭代理缓冲 |
| 用户体验 | 先显示加载动画，再逐 token 显示文本，并提供停止按钮 |
| 成本 | 追踪输入/输出 token、设置 max_tokens、取消无效会话 |
| 可靠性 | 只重试可重试的错误、保留部分文本、用续写提示词重启 |
所以如果由我来搭建，我会把流式传输当作一项 用户体验与基础设施的选择，而不仅仅是一个 API 开关。
使用 Claude API 构建应用 - 第 4 部分 - 响应流式传输
Claude API 流式传输在协议层的工作原理
打开流式传输不会改变模型本身，它改变的是输出如何被传递。Claude 不再等待一条完整响应，而是在每个块就绪时就发送出去。
哪个端点和请求设置能启用流式传输
流式传输使用与普通请求相同的 Claude Messages API 端点 /v1/messages。唯一的区别是在请求体中加入 "stream": true [1][3]。这个标志会把连接从标准的请求-响应流程切换为 Server-Sent Events (SSE)，服务器会在块生成时逐一推送。
官方的 Python 和 TypeScript SDK 都包含流式辅助工具，能替你处理事件解析和消息组装。当流结束时，在 Python 中调用 .get_final_message()、在 TypeScript 中调用 .finalMessage()，即可返回完整的响应，以及 token 计数和停止原因 [1][4]。
这些设置会启动流。下一环节是通过该连接返回的事件流。
流式过程中会到达哪些事件
一条流会遵循一组既定顺序的命名事件。每个事件携带着客户端正确重建完整响应所需的数据。
| 事件类型 | 用途 | 关键数据 |
|---|---|---|
message_start | 打开流 | 消息 ID、角色、模型和 input_tokens |
content_block_start | 开始一个新的内容段 | 块索引和块类型（text、tool_use 或 thinking） |
content_block_delta | 发送部分内容 | 块索引和 text_delta、input_json_delta 或 thinking_delta |
content_block_stop | 关闭一个内容段 | 已完成块的索引 |
message_delta | 更新消息级状态 | 累计的 output_tokens 和 stop_reason |
message_stop | 结束流 | 关闭连接的最终信号 |
ping | 心跳 | 在模型处理期间发送 |
error | 报告流错误 | 错误类型和消息 |
这些正是客户端缓冲并实时展示的数据。对于纯文本输出，在事件到达时把每个 text_delta 追加到本地缓冲区，完整的响应字符串就是这样一片片拼起来的。工具调用的输入方式略有不同：它们以 input_json_delta 片段的形式到达，所以你应先缓冲它们，并且只在 content_block_stop 之后再解析 [1][6]。
什么时候 APIMart 对 Claude 流式传输有意义
如果 Claude 流式传输位于一个多模型应用中，APIMart 可以让你在一个地方，通过统一的 LLM API 路由 Claude 的访问和流式传输。当你希望在 Web 和移动客户端之间保持同一套流式流程时，这一点往往最为关键。
如何为 Web 和移动应用添加 Claude 流式传输
SSE、HTTP 流式传输还是 WebSocket 封装：该用哪一个
一旦你理解了 Claude 如何发送流式事件，下一步就是把这些事件传递给 Web 和移动客户端。核心问题很简单：哪种传输方式最适合你的应用？
| 传输方式 | 配置复杂度 | 浏览器契合度 | 连接行为 |
|---|---|---|---|
| Server-Sent Events (SSE) | 低 | 原生（EventSource/Fetch） | 单向；自动重连 |
| 纯 HTTP 流式传输 | 中 | 需要 ReadableStream | 无内置事件结构或重连 |
| WebSocket 封装 | 高 | 需要库/封装 | 双向；有状态；可能被某些企业防火墙拦截 |
对大多数基于浏览器的应用，SSE 是默认选择。它与大多数代理和 CDN 配合良好，浏览器支持也很简单。
WebSocket 仍然有其适用场景。如果你的应用本就依赖双向、实时的通信，它可能正好契合。但对一个标准的聊天应用来说，它往往带来的复杂度多于它的价值。
为什么后端代理通常是最安全的架构
选定传输方式后，把流处理放在你的服务器之后。将 Claude 请求放在后端代理之后，以保护你的各类模型的 API 密钥 [9][5]。
那一层代理也是执行以下操作的合适位置：
- 注入系统提示词
- 实施按用户的速率限制
- 记录首个 token 和最后一个 token 的时间
设置 X-Accel-Buffering: no 以停止代理缓冲 [2][8]。同时把客户端的中止信号连接到流上。这样，如果用户停止生成，请求会立即被取消，而不是继续在没人会读的响应上消耗 token。
还有一个陷阱：30–60 秒的默认超时可能会截断较长的响应 [9][2]。在生产环境中，对较长的生成使用约 120–300 秒的读取超时。
实时响应期间良好的客户端体验是什么样的
一旦流被保护并转发，工作重心就转向了 UI。这里正是决定流式体验流畅还是卡顿的地方。
用户一提交提示词，就立即显示一个 “Thinking...” 提示或加载动画，以覆盖首个 token 的延迟。一旦第一个 content_block_delta 到达，就移除该提示并开始渲染文本。
然后在每个 text_delta 到达时追加它，让响应呈现出打字机效果。为避免界面抖动，用 requestAnimationFrame 批量更新，这样就不会触发过多的重新渲染。在响应生成期间，自动滚动应跟随响应；但如果用户向上滚动去阅读较早的内容，自动滚动就应当退让。
始终包含一个连接到 AbortController 的 “Stop” 按钮，以便取消 Fetch 请求。它应当干净地结束流，同时不抹掉屏幕上已有的文本。
如果连接断开，让部分输出继续可见。为了恢复，保留那段部分文本，并用续写提示词重新开始，因为 Claude 原生不会恢复一条已断开的流 [3][1]。
如何在生产环境中管理延迟、成本与可靠性
一旦流上线，生产工作就归结为三项控制：延迟、开销和恢复。
流式传输如何改变感知到的延迟
这里最主要的用户体验指标是 首个 token 到达时间 (TTFT)：直到第一个词出现的时间。在一个流式应用中，那第一个可见的 token 塑造了整个产品的感觉。如果它出现得快，应用就显得灵敏；如果它拖沓，用户会注意到。
基准测试显示各 Claude 模型之间存在明显差距：Haiku 4.5 的 TTFT 约为 410 ms，Sonnet 4.6 约为 720 ms，而 Opus 4.7 约为 980 ms [3]。简单的规则是：使用仍能达到你质量标准的最快模型。
提示词大小同样重要。更大的上下文窗口会把 TTFT 推向 1–3 秒 [5]。所以如果你的系统提示词里有多余的指令、过时的规则或臃肿的示例，把它们删掉可以让应用感觉灵敏得多。
如何追踪 token 用量并控制美元成本
流式和批处理的每 token 成本相同，唯一改变的是输出到达的时机。token 计数就包含在流本身中：message_start 事件包含 usage.input_tokens，而临近结尾的 message_delta 事件包含最终累计的 usage.output_tokens [1][4]。你的后端应在流结束后存储这份最终用量数据，以保证计费准确。
在每个请求上设置 max_tokens。它给你一个硬性上限，避免长时间生成推高成本 [1][11]。你还应在服务器端留意客户端断连。如果用户已经离开而生成仍在继续，你就在毫无理由地继续消耗 token [5][7]。
对于不需要实时输出的任务，账算法就不同了。批量摘要、离线处理和隔夜报告生成都是很好的例子。在这些情况下，Batch API 在正常 token 费率上提供 50% 的折扣 [5][10]。
Claude 3.5 Sonnet 在标准流式传输下，每 100 万输入 token 约 $3.00、每 100 万输出 token 约 $15.00 [8]。使用 Batch API，异步工作负载的成本只有一半。
这些用量数字也有助于计费和速率限制监控。想了解更多管理高并发请求的策略，请参阅我们的 AI API 成本建议。
如何防止断流并安全恢复
Claude 没有服务端恢复功能 [1][3]。如果一条流断了，就在一个新请求中发送部分输出，并让 Claude 从中断点继续。
只重试那些很可能会自行清除的失败。
| 错误码 | 类型 | 处理方式 |
|---|---|---|
| 429 | 速率限制 | 带退避重试：5s → 10s → 20s |
| 529 | 服务器过载 | 30–60 秒后重试 |
| 408 | 连接超时 | 立即重连 |
| 4xx | 客户端错误 | 不要重试；修正请求 |
在此之后，最后一步是选择哪些流式特性最重要。
结论：哪些 Claude 流式特性最重要
在你审视过延迟、成本和可靠性之后，Claude 流式传输可以归结为三件事：感知到的响应速度、清晰的事件信号，以及扎实的错误处理。
流式传输之所以重要，是因为首个 token 的传递让 Claude 显得快速而灵敏。
SSE 事件流实时地给你文本增量、用量计数和错误信号 [1][3]。
用后端代理来保护密钥、关闭缓冲并处理断连 [2][8]。对于多模型应用，APIMart 可以集中处理 Claude 的流式传输、日志和计费。
在生产环境中，快速的 TTFT、用量追踪和代理的韧性最为重要。
常见问题
我应该在什么时候用流式传输而不是普通的 Claude API 响应？
当你的应用面向用户时，使用流式传输。它在 token 生成时就发送出去，所以响应几乎是即时的。这个小小的转变能让整个产品感觉更快、更流畅。
流式传输最适合实时聊天、长答案，以及带工具调用的智能体工作流。当输出较长或 token 上限较高时，它还能帮你避免超时。
对于简短、简单的请求，或吞吐量比延迟更重要的批处理任务，则跳过它。
如果一条 Claude 流在响应中途断开，我该怎么办？
如果一条 Claude 流断开，Server-Sent Events 不会自己从中断处接续。这部分需要你的应用来处理。
当连接断开时，你可以重试整个请求，或展示你已经保存的部分输出。用一个 try/except 块来捕获 APIConnectionError 或 APIStatusError，并保留一个对你目前已累积内容的引用。
如果你希望流以更少的摩擦继续，就追踪最后一个事件 ID，并从该点手动重放流。
我如何在不损害用户体验的前提下降低流式成本？
聚焦于提示词调优和高效的会话处理。设置 max_tokens 硬性上限、保持提示词简短，并加入一个提前取消的选项，让用户在拿到所需内容后就能停止生成。
对于不需要即时来回交互的批量工作负载，使用非流式模式。为了准确追踪成本，等待最终的 message_stop 事件，而不是从中途的块去估算。
去模型市场挑选你想要的模型
在 APIMart 模型市场尝试聊天、图像和视频模型，用统一 API 快速体验模型能力。