Streaming API

在 Claude 生成内容时逐步接收响应：启用 stream: true、处理 SSE 事件顺序、累积 text_delta，并正确处理完成与错误。

更新于：2026 年 7 月 25 日。

如何启用 Streaming

在普通 Messages API 请求中添加 stream: true。服务器将返回 Server-Sent Events 流，而不是单个 JSON 响应。

Request body

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 512,
  "stream": true,
  "messages": [
    {"role": "user", "content": "Explain SSE in one paragraph"}
  ]
}

Anthropic 与 OpenAI-compatible

两种格式都支持 stream: true。Anthropic /v1/messages endpoint 返回具名 SSE 事件，OpenAI-compatible /v1/chat/completions endpoint 返回 data chunks，并以 [DONE] 结束。

通过 SDK 和 cURL 使用 Streaming

Anthropic SDK 会解析 SSE 并提供便捷的文本流。直接使用 HTTP 时，cURL 会显示原始 event 和 data 行。

stream.sh

curl https://api.llm-gate.tech/v1/messages \  --header "x-api-key: $CLAUDE_API_KEY" \  --header "anthropic-version: 2023-06-01" \  --header "content-type: application/json" \  --no-buffer \  --data '{    "model": "claude-sonnet-4-6",    "max_tokens": 512,    "stream": true,    "messages": [      {"role": "user", "content": "Explain SSE in one paragraph"}    ]  }'

SSE 事件顺序

每个流以 message_start 开始，包含一个或多个 content blocks，并以 message_stop 结束。中间可能出现 ping。

message_start — content 数组为空的 Message 对象。
content_block_start — text、tool_use 或 thinking block 开始。
content_block_delta — block 的下一段增量内容。
content_block_stop — block 已完整传输。
message_delta — stop_reason 和累计 usage 更新。
message_stop — 流成功结束。

完整 HTTP stream response

直接集成 HTTP 时，应按顺序读取 SSE 行。event 字段表示事件类型，data 行包含具有相同 type 的 JSON。

text/event-stream

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","content":[]}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":8}}

event: message_stop
data: {"type":"message_stop"}

主要 Delta 类型

Delta	内容	处理方式
text_delta	生成文本片段	将 delta.text 追加到显示文本。
input_json_delta	tool_use 的部分 JSON	累积 partial_json，并在 content_block_stop 后解析。
thinking_delta	流式 thinking content	仅在 thinking 已启用且可用时处理。
signature_delta	thinking block 签名	在 content_block_stop 前原样保留。

何时视为响应完成

不要在第一个文本或 content_block_stop 后停止。只有收到 message_stop 才表示完整响应已就绪。message_delta 中的 usage 是累计值。

按 index 累积 blocks；它对应最终 content 数组中的位置。
安全忽略 ping 和未来未知 event types，不要让解析器崩溃。
如需最终 Message 对象，TypeScript 使用 finalMessage()，Python 使用 get_final_message()。

Streaming response 中的错误

请求可能先返回 HTTP 200，之后收到 event: error。例如，流中的 overloaded_error 等同于非流式响应中的 HTTP 529。部分文本不能视为完整响应。

SSE

event: error
data: {
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Overloaded"
  }
}

Claude API 错误参考

← Messages API API 错误 →