Claude Platform Docs
Messages模型功能

串流訊息

使用伺服器傳送事件以增量方式串流 Messages API 回應，包括文字、工具使用及擴展思考的增量內容。

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

使用 SDK 進行串流

Python SDK 與 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-5-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

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

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

client = anthropic.Anthropic()

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

for block in message.content:
    if block.type == "text":
        print(block.text)

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

事件類型

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

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

  1. message_start：包含一個 content 為空的 Message 物件。在 thinking-binding-controls-2026-08-01 beta 標頭下，此 Message 物件也會帶有 input_transformations 陣列。在串流中途發生伺服器端回退之後，最終的 message_delta 事件會再次帶有該陣列，其中包含實際提供服務之模型的項目。
  2. 一系列內容區塊，每個區塊都有一個 content_block_start、一個或多個 content_block_delta 事件，以及一個 content_block_stop 事件。每個內容區塊都有一個 index，對應其在最終 Message content 陣列中的索引。有一個例外：在伺服器端回退回應期間，fallback 內容區塊會在每個模型邊界處以一對 content_block_start 與 content_block_stop 的形式抵達，中間沒有任何增量事件。
  3. 一個或多個 message_delta 事件，表示對最終 Message 物件的頂層變更。
  4. 最終的 message_stop 事件。

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 字串為空的 thinking_delta，接著接收單一的 signature_delta，然後關閉。使用 display: "updates"（beta）時，推理區塊會以相同方式串流，只有部分模型在工具呼叫之間撰寫的進度更新會串流帶有文字的 thinking_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 整合，則需要自行處理這些事件。

串流回應由以下部分組成：

  1. 一個 message_start 事件
  2. 可能有多個內容區塊，每個區塊包含：
    • 一個 content_block_start 事件
    • 可能有多個 content_block_delta 事件
    • 一個 content_block_stop 事件
  3. 一個或多個 message_delta 事件
  4. 一個 message_stop 事件

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

基本串流請求

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=256,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
Response
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "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"}

包含工具使用的串流請求

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

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-5",
    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)
Response
event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-5","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 推理的精簡摘要，而非完整的思考鏈。

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    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":
            delta = event.delta
            match delta.type:
                case "thinking_delta":
                    print(delta.thinking, end="", flush=True)
                case "text_delta":
                    print(delta.text, end="", flush=True)
Response
event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "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 在網路上搜尋目前的天氣資訊。

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    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)
Response
event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-5-5","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 及更早的模型，若串流請求因網路問題、逾時或其他錯誤而中斷，您可以從串流中斷處繼續，以復原該請求。此方法可讓您免於重新處理整個回應。

基本的復原策略包括：

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

Claude 4.6 及更新版本

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

  1. 擷取部分回應：儲存在錯誤發生前已成功接收的所有內容。
  2. 建構接續請求：建立一個新的 API 請求，其中包含一則 user 訊息，內含部分回應以及繼續的指示，例如：
    Sample prompt
    Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.
  3. 繼續串流：從中斷處繼續接收回應的其餘部分。

錯誤復原最佳實務

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

後續步驟

停止原因與回退

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

細粒度工具串流

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

思考

透過 thinking_delta 與 signature_delta 事件串流思考輸出。

用戶端 SDK

使用官方 SDK，它們會為您處理串流、累積與重新連線。

批次處理

當您不需要即時回應時，以非同步方式處理大量請求。

Was this page helpful?