串流訊息 - Claude Platform Docs

建立 Message 時，您可以設定 "stream": true，以使用「server-sent events」（伺服器傳送事件），即 SSE 逐步串流回應。

使用 SDK 進行串流

Python 和 TypeScript SDK 提供多種串流方式。PHP SDK 透過 createStream() 提供串流功能。Python SDK 同時支援同步和非同步串流。詳情請參閱各 SDK 的文件。

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-4-8",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

取得最終訊息而不處理事件

如果您不需要在文字到達時即時處理，SDK 提供了一種在底層使用串流的同時回傳完整 Message 物件的方式，與 .create() 回傳的內容相同。這對於 max_tokens 值較大的請求特別有用，因為 SDK 需要使用串流來避免 HTTP 逾時。

.stream() 呼叫會透過伺服器傳送事件保持 HTTP 連線，然後 .get_final_message()（Python）或 .finalMessage()（TypeScript）會累積所有事件並回傳完整的 Message 物件。在 Go 中，您在串流迴圈內呼叫 message.Accumulate(event) 來建立相同的完整 Message。在 Java 中，使用 MessageAccumulator.create() 並對每個事件呼叫 accumulator.accumulate(event)。在 C# 中，對串流的 .Aggregate() 擴充方法使用 await 以取得完整的 Message，或將 MessageContentAggregator 傳遞給 .CollectAsync() 以在處理事件的同時進行累積。在 Ruby 中，對串流呼叫 .accumulated_message。在 PHP SDK 中，您需要手動迭代串流事件以累積回應。

事件類型

每個伺服器傳送事件都包含一個具名的事件類型和相關的 JSON 資料。每個事件使用一個 SSE 事件名稱（例如 event: message_stop），並在其資料中包含對應的事件 type。

每個串流使用以下事件流程：

message_start：包含一個 content 為空的 Message 物件。
一系列內容區塊，每個區塊都有一個 content_block_start、一個或多個 content_block_delta 事件，以及一個 content_block_stop 事件。每個內容區塊都有一個 index，對應於最終 Message content 陣列中的索引。有一個例外：在伺服器端備援回應期間，fallback 內容區塊會在每個模型邊界以 content_block_start 和 content_block_stop 配對的形式到達，中間沒有任何增量（delta）。
一個或多個 message_delta 事件，表示對最終 Message 物件的頂層變更。
最後一個 message_stop 事件。

message_delta 事件的 usage 欄位中顯示的 token 計數是累計的。

Ping 事件

事件串流也可能包含任意數量的 ping 事件。

錯誤事件

API 可能偶爾會在事件串流中傳送錯誤。例如，在高使用量期間，您可能會收到 overloaded_error，這在非串流情境下通常對應於 HTTP 529：

Example error

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

其他事件

根據版本控制政策，可能會新增新的事件類型，您的程式碼應能妥善處理未知的事件類型。

內容區塊增量類型

每個 content_block_delta 事件都包含一個特定類型的 delta，用於更新指定 index 處的 content 區塊。

文字增量

text 內容區塊增量如下所示：

Text delta

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

輸入 JSON 增量

tool_use 內容區塊的增量對應於該區塊 input 欄位的更新。為了支援最大粒度，這些增量是部分 JSON 字串，而最終的 tool_use.input 始終是一個物件。

您可以累積字串增量，並在收到 content_block_stop 事件後解析 JSON，方法是使用像 Pydantic 這樣的函式庫進行部分 JSON 解析，或使用 SDK，它們提供了存取已解析增量值的輔助工具。

tool_use 內容區塊增量如下所示：

Input JSON delta

event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

注意：目前的模型一次只支援從 input 發出一個完整的鍵和值屬性。因此，在使用工具時，模型運作期間串流事件之間可能會有延遲。一旦累積了一個 input 鍵和值，它們會以多個包含分塊部分 JSON 的 content_block_delta 事件發出，以便此格式能自動支援未來模型中更細的粒度。

思考增量

當啟用串流並使用擴展思考時，您將透過 thinking_delta 事件接收思考內容。這些增量對應於 thinking 內容區塊的 thinking 欄位。

對於思考內容，會在 content_block_stop 事件之前傳送一個特殊的 signature_delta 事件。此簽章用於驗證思考區塊的完整性。

當思考設定中設定了 display: "omitted" 時，不會傳送任何 thinking_delta 事件。思考區塊會開啟、接收單一 signature_delta，然後關閉。請參閱控制思考顯示。

典型的思考增量如下所示：

Thinking delta

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

簽章增量如下所示：

Signature delta

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

完整的 HTTP 串流回應

使用串流模式時，請使用用戶端 SDK。但是，如果您正在建立直接的 API 整合，則需要自行處理這些事件。

串流回應包含：

一個 message_start 事件
可能有多個內容區塊，每個區塊包含：
- 一個 content_block_start 事件
- 可能有多個 content_block_delta 事件
- 一個 content_block_stop 事件
一個或多個 message_delta 事件
一個 message_stop 事件

回應中也可能穿插 ping 事件。有關格式的更多詳細資訊，請參閱事件類型。

基本串流請求

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

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

event: ping
data: {"type": "ping"}

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

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

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

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

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

使用工具的串流請求

工具使用支援參數值的細粒度串流。透過 eager_input_streaming 為每個工具啟用此功能。

此請求要求 Claude 使用工具來回報天氣。

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-4-8","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

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

event: ping
data: {"type": "ping"}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\"}"}}

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

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

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

使用擴展思考的串流請求

此請求啟用了帶有串流的擴展思考。display: "summarized" 設定會串流 Claude 推理過程的精簡摘要，而非完整的思考鏈。

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "stop_reason": null, "stop_sequence": null}}

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n147 = 7 × 21 + 0"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\nThe remainder is 0, so GCD(1071, 462) = 21."}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

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

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

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

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

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

使用網路搜尋工具的串流請求

此請求要求 Claude 搜尋網路以取得目前的天氣資訊。

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-4-8","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":2679,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3}}}

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":"I'll check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the current weather in New York City for you"}}

event: ping
data: {"type": "ping"}

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

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

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"query"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" NY"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"C to"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"day\"}"}}

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

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"web_search_tool_result","tool_use_id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","content":[{"type":"web_search_result","title":"Weather in New York City in May 2025 (New York) - detailed Weather Forecast for a month","url":"https://world-weather.info/forecast/usa/new_york/may-2025/","encrypted_content":"Ev0DCioIAxgCIiQ3NmU4ZmI4OC1k...","page_age":null},...]}}

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

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

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Here's the current weather information for New York"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" City:\n\n# Weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" in New York City"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"\n\n"}}

...

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

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":10682,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":510,"server_tool_use":{"web_search_requests":1}}}

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

錯誤復原

Claude 4.5 及更早版本

對於 Claude 4.5 及更早的模型，您可以從串流中斷的位置繼續，以復原因網路問題、逾時或其他錯誤而中斷的串流請求。此方法可讓您免於重新處理整個回應。

基本的復原策略包括：

擷取部分回應： 儲存錯誤發生前已成功接收的所有內容
建構接續請求： 建立一個新的 API 請求，將部分助理回應作為新助理訊息的開頭
繼續串流： 從中斷的位置繼續接收其餘的回應

Claude 4.6 及更新版本

對於 Claude 4.6 及更新的模型，同樣適用擷取並繼續的策略，但步驟 2 有所變更：不是將部分回應放在助理訊息中，而是新增一個使用者訊息，指示模型從中斷處繼續。

擷取部分回應： 儲存錯誤發生前已成功接收的所有內容
建構接續請求： 建立一個新的 API 請求，其中包含一個使用者訊息，該訊息包含部分回應和繼續的指示，例如：
Sample prompt
```
Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.
```
繼續串流： 從中斷的位置繼續接收其餘的回應

錯誤復原最佳實務

使用 SDK 功能： 善用 SDK 內建的訊息累積和錯誤處理功能
處理內容類型： 請注意訊息可能包含多個內容區塊（text、tool_use、thinking）。工具使用和擴展思考區塊無法部分復原。您可以從最近的文字區塊繼續串流。

後續步驟

停止原因與備援

在串流完成後處理每個 stop_reason 值。

細粒度工具串流

串流工具輸入 JSON 而無需伺服器端緩衝，以降低延遲。

擴展思考

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-opus-4-8",
) as stream:
    message = stream.get_final_message()

print(message.content[0].text)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=256,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "any"},
    messages=[
        {"role": "user", "content": "What is the weather like in San Francisco?"}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=20000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
    messages=[
        {"role": "user", "content": "What is the weather like in New York City today?"}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

使用 SDK 進行串流

取得最終訊息而不處理事件

事件類型

Ping 事件

錯誤事件

其他事件

內容區塊增量類型

文字增量

輸入 JSON 增量

思考增量

完整的 HTTP 串流回應

基本串流請求

使用工具的串流請求

使用擴展思考的串流請求

使用網路搜尋工具的串流請求

錯誤復原

Claude 4.5 及更早版本

Claude 4.6 及更新版本

錯誤復原最佳實務

後續步驟

使用 SDK 進行串流

取得最終訊息而不處理事件

事件類型

Ping 事件

錯誤事件

其他事件

內容區塊增量類型

文字增量

輸入 JSON 增量

思考增量

完整的 HTTP 串流回應

基本串流請求

使用工具的串流請求

使用擴展思考的串流請求

使用網路搜尋工具的串流請求

錯誤復原

Claude 4.5 及更早版本

Claude 4.6 及更新版本

錯誤復原最佳實務

後續步驟