串流事件

stream: true 時三種協定的 SSE 事件格式、HopBase 插入的保活註解，以及串流中錯誤的傳送方式。

請求體傳 "stream": true 後，建立對話補全、建立回應與建立訊息改為回傳 text/event-stream（SSE）。事件格式沿用各協定官方定義，官方 SDK 的串流介面可以直接使用；HopBase 只在其中插入保活註解，不改動事件內容。

POST/v1/chat/completionsPOST/v1/responsesPOST/v1/messages

保活註解

串流期間 HopBase 約每 10 秒在兩個事件之間寫入一行 SSE 註解，避免長推理時連線被中間代理判為閒置而斷開：

: hopbase-keepalive

以冒號開頭的行是 SSE 規範裡的註解，官方 SDK 與標準 SSE 解析器都會忽略；自行逐行解析時，請跳過以 : 開頭的行，不要當作 JSON 解析。模型長時間沒有任何輸出時（約 90～150 秒，依模型而異），網關判定卡住並重試或報錯，詳見並行、逾時與計費。

Chat Completions

每個事件一行 data:，內容是 chat.completion.chunk 物件，文字在 choices[0].delta.content；最後以 data: [DONE] 結束。

data: {"id":"chatcmpl-EXAMPLE","object":"chat.completion.chunk","model":"gpt-5.6-sol","choices":[{"index":0,"delta":{"role":"assistant","content":"我是"},"finish_reason":null}]}

data: {"id":"chatcmpl-EXAMPLE","object":"chat.completion.chunk","model":"gpt-5.6-sol","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-EXAMPLE","object":"chat.completion.chunk","model":"gpt-5.6-sol","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":52,"total_tokens":66}}

data: [DONE]

欄位	說明
`choices[].delta.content`	本段文字
`choices[].delta.tool_calls`	工具呼叫參數分段傳送，依 `index` 拼接 `function.arguments`
`choices[].finish_reason`	最後一段非空：`stop` / `length` / `tool_calls`
`usage`	只有請求傳了 `stream_options.include_usage: true` 才傳送，在最後一個 `choices` 為空的事件裡；不傳不影響計費

Responses

每個事件由 event: 行和 data: 行組成，data 裡的 type 與事件名稱相同。

event: response.created
data: {"type":"response.created","response":{"id":"resp_EXAMPLE","status":"in_progress"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_EXAMPLE","output_index":0,"content_index":0,"delta":"我是"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_EXAMPLE","status":"completed","usage":{"input_tokens":14,"output_tokens":58,"total_tokens":72}}}

事件	說明
`response.created`	回應開始
`response.output_text.delta`	一段輸出文字，在 `delta`
`response.output_text.done`	一段內容結束，`text` 為完整文字
`response.completed`	成功結束，`response.usage` 為用量
`response.failed`	中途失敗，原因在 `response.error.code`：`rate_limit_exceeded` / `server_error` / `invalid_prompt`

Anthropic Messages

事件順序：message_start → 每個內容區塊 content_block_start / content_block_delta / content_block_stop → message_delta（帶 stop_reason 與輸出用量）→ message_stop。

event: message_start
data: {"type":"message_start","message":{"id":"msg_EXAMPLE","role":"assistant","model":"claude-sonnet-5","content":[],"usage":{"input_tokens":9,"output_tokens":1}}}

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

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

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

串流中錯誤

串流一旦開始輸出，HTTP 狀態碼就已是 200，之後的錯誤透過事件傳送，不會再改狀態碼：

Chat Completions   data: {"error": {…}}      （不帶 event: 行）
Responses          event: response.failed
Anthropic          event: error

Claude 串流在中途斷開時，HopBase 會補發一條 Anthropic 錯誤事件後結束：

event: error
data: {"type":"error","error":{"type":"api_error","message":"Response stream interrupted, please retry"}}

用戶端要在讀取串流的迴圈裡處理錯誤事件。已收到的片段無法續傳，需要整筆請求重新發起；中斷前已產出的部分依用量計費。重試策略見錯誤碼與重試。

保活註解

Chat Completions

Responses

Anthropic Messages

串流中錯誤

本頁目錄