Claude 原生格式：流式與非流式響應

通過 Claude 原生格式（/v1/messages）呼叫時，響應結構與 OpenAI 相容格式完全不同：正文是按型別區分的 content 塊陣列，流式則用 Anthropic 的具名事件 SSE 協議。本頁講清兩種模式怎麼解析。

請求側（端點、anthropic-version 頭、x-api-key 鑑權、effort / thinking 引數）見 Claude API 基礎說明與 Claude Effort 思考指南。本頁只講響應側。示例用輕量模型 claude-haiku-4-5-20251001。

非流式響應

頂層是一個 message 物件，正文在 content 陣列裡，按 type 區分塊：

{
  "id": "msg_bdrk_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-haiku-4-5-20251001",
  "content": [
    { "type": "text", "text": "1+1等於2。" }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 26,
    "output_tokens": 11,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

取正文要遍歷 content 陣列——不能像 OpenAI 那樣直接取一個字串欄位：

import requests

resp = requests.post(
    "https://api.apiyi.com/v1/messages",
    headers={
        "content-type": "application/json",
        "anthropic-version": "2023-06-01",
        "x-api-key": "YOUR_API_KEY",
    },
    json={
        "model": "claude-haiku-4-5-20251001",
        "max_tokens": 100,
        "messages": [{"role": "user", "content": "1+1等於幾？"}],
    },
    timeout=60,
)
data = resp.json()
for block in data["content"]:
    if block["type"] == "text":
        print(block["text"])
    elif block["type"] == "thinking":      # 開啟思考時才有
        print("[思考]", block["thinking"])
print(data["usage"])

curl https://api.apiyi.com/v1/messages \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "1+1等於幾？"}]
  }'

stop_reason 取值：end_turn（正常結束）、max_tokens（被 max_tokens 截斷，正文可能為空，調大即可）、stop_sequence、tool_use（要呼叫工具）。開啟思考後，content 數組裡會多出 type: "thinking" 的塊，排在 text 塊之前。

流式響應（具名事件 SSE）

Claude 流式用的是 Anthropic 事件協議：每條訊息有 event: 名稱 + data: 負載，需要按事件型別分發，而不是像 OpenAI 那樣每塊都同構。

event: message_start
data: {"type":"message_start","message":{"id":"...","content":[],"usage":{"input_tokens":26,"output_tokens":8}}}

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":"1+1等於2。"}}

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":11}}

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

事件流的固定順序與職責：

事件	作用
`message_start`	訊息骨架；`usage.input_tokens` 和初始 `output_tokens` 在此
`content_block_start`	一個內容塊開始（`index` + 塊型別 text / thinking）
`content_block_delta`	增量；正文是 `delta.type == "text_delta"` 的 `delta.text`
`content_block_stop`	當前塊結束
`message_delta`	最終 `stop_reason` + 累計的 `output_tokens` 在此
`message_stop`	整條訊息結束（無 `[DONE]`，以此事件為終止訊號）

解析的核心是累加 content_block_delta 裡的 text_delta：

import json, requests

resp = requests.post(
    "https://api.apiyi.com/v1/messages",
    headers={
        "content-type": "application/json",
        "anthropic-version": "2023-06-01",
        "x-api-key": "YOUR_API_KEY",
    },
    json={
        "model": "claude-haiku-4-5-20251001",
        "max_tokens": 100,
        "stream": True,
        "messages": [{"role": "user", "content": "寫一首短詩"}],
    },
    stream=True, timeout=120,
)

text, usage = "", {}
for line in resp.iter_lines(decode_unicode=True):
    if not line or not line.startswith("data: "):
        continue                       # event: 行可跳過，型別也在 data 的 "type" 裡
    evt = json.loads(line[6:])
    t = evt["type"]
    if t == "message_start":
        usage.update(evt["message"]["usage"])
    elif t == "content_block_delta" and evt["delta"]["type"] == "text_delta":
        piece = evt["delta"]["text"]
        text += piece
        print(piece, end="", flush=True)
    elif t == "message_delta":
        usage.update(evt["usage"])     # 最終 output_tokens
    elif t == "message_stop":
        break                          # 終止訊號，無 [DONE]

事件型別在 event: 行和 data: 負載的 "type" 欄位裡都有，按任一個分發都行。用官方 anthropic SDK 時，把 base_url 指向 https://api.apiyi.com 即可，SDK 會自動處理事件流，無需手寫上面的迴圈。

開啟思考（adaptive thinking）時，會先出現 type: "thinking" 的內容塊，其增量是 thinking_delta，並在塊結束前出現一個 signature_delta（思考塊簽名）。展示思考時把 thinking_delta 與 text_delta 分流渲染即可。思考用法見 Claude Effort 思考指南。

與 OpenAI 相容格式的關鍵差異

維度	Claude 原生（`/v1/messages`）	OpenAI 相容（`/v1/chat/completions`）
正文位置	`content` 塊陣列，按 `type` 區分	`choices[0].message.content` 字串
流式協議	具名事件（`event:` + `data:`）	同構 chunk 物件
流式終止	`message_stop` 事件，無 `[DONE]`	`data: [DONE]`
增量欄位	`content_block_delta.delta.text`	`choices[0].delta.content`
usage 欄位	`input_tokens` / `output_tokens`（分散在 message_start 與 message_delta）	`prompt_tokens` / `completion_tokens` / `total_tokens`
結束原因	`stop_reason`（`end_turn` 等）	`finish_reason`（`stop` 等）
`max_tokens`	必填	選填

遷移最容易踩的兩點：① 正文是陣列不是字串，必須遍歷 content 取 type=="text" 的塊；② 流式沒有 [DONE]，要用 message_stop 事件判結束。

usage 與計費

非流式：usage 隨結果返回，含 input_tokens、output_tokens、cache_creation_input_tokens、cache_read_input_tokens。
流式：input_tokens 在 message_start，最終 output_tokens 在 message_delta，需兩處合併。
快取命中欄位（cache_read_input_tokens）的折扣與用法見 Claude 快取計費。

產品基礎

基礎 API

圖片 API（官轉）

影片 API（官轉）

多模態理解 API

文本 API

Claude 原生格式：流式與非流式響應

非流式響應

流式響應（具名事件 SSE）

與 OpenAI 相容格式的關鍵差異

usage 與計費

相關連結

​非流式響應

​流式響應（具名事件 SSE）

​與 OpenAI 相容格式的關鍵差異

​usage 與計費

​相關連結

非流式響應

流式響應（具名事件 SSE）

與 OpenAI 相容格式的關鍵差異

usage 與計費

相關連結