Claude Sonnet 5.5
Claude Sonnet 5.5 Messages API 參考：官方參數、自適應思考與工具呼叫之間的思考模式、提示快取用量、回應欄位，以及實測的相容性限制。
以 Anthropic Messages 格式呼叫 claude-sonnet-5-5。本文件分別說明官方請求規範與相容性測試中觀察到的行為。部分進階選項目前尚未依規範運作；使用前請先確認相關限制。
請參閱模型頁，查看目前的輸入、輸出與快取價格。
快速範例
curl https://api.seedrouter.ai/v1/messages \
-H "x-api-key: $SEEDROUTER_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Explain how a rainbow forms in three sentences."}]
}'POST /v1/messages 接受 x-api-key 或 Bearer 驗證，並使用 anthropic-version: 2023-06-01。若功能的官方文件要求 beta 標頭，請傳送 anthropic-beta。憑證應保存在伺服器端程式碼中。
此模型也接受基本的 OpenAI Chat Completions（POST /v1/chat/completions）與 Responses（POST /v1/responses）請求。使用下列原生參數時，請採用 Messages 格式；OpenAI 格式轉換並未涵蓋 Anthropic 的所有功能。
官方參數規範
Sonnet 5.5 的上下文視窗為 1M token，同步請求的輸出上限為 128000 token。Batch 專用的輸出限制不適用於此端點。除非下表另有說明，應用程式不會主動為選填屬性設定預設值。
| 參數 | 型別 / 必填與否 | 官方限制與預設值 |
|---|---|---|
model | string，必填 | claude-sonnet-5-5。 |
max_tokens | integer，必填 | 0–128000，包含思考 token。依官方定義，0 會填入提示快取而不產生輸出；請參閱下文的目前限制。 |
messages | object 陣列，必填 | 至少一則對話訊息，最多 100000 則。每則包含 role 與 content；content 可為字串或內容區塊陣列。一般對話輪次使用 user/assistant。對話中途的 system 訊息須遵循官方的位置規則。 |
system | string 或文字區塊陣列 | 頂層指令。文字區塊可包含快取中斷點。 |
thinking | object | 預設：{"type":"adaptive"}。另一種支援的模式為 {"type":"between_tools"}。手動預算與 disabled 皆會遭到拒絕。 |
thinking.display | enum | 僅適用於自適應模式：omitted（預設）或 summarized。省略摘要不表示已停用思考。 |
thinking.block_binding | object，beta | 僅適用於自適應模式。需要 thinking-binding-controls-2026-08-01；請遵循官方保留思考內容的規範。 |
output_config.effort | enum 或 null | low、medium、high、xhigh、max；預設為 high。Null 會保留預設行為。 |
output_config.format | object 或 null | JSON 結構化輸出：{"type":"json_schema","schema":{...}}。請使用支援的 JSON Schema 子集。 |
stream | boolean | 預設為 false；true 會回傳 SSE 事件。 |
stop_sequences | string 陣列 | 依官方定義，遇到符合的字串時停止生成。目前的相容性測試未落實此行為。 |
temperature | number 或 null | 僅為相容性接受 1；請省略此項。其他非 null 值會遭到拒絕。 |
top_p | number 或 null | 僅為相容性接受 0.99–1；請省略此項。 |
top_k | 不接受非 null 值 | 不支援取樣設定；請省略此屬性。 |
tools | object 陣列 | 用戶端工具包含 name、input_schema，以及選填的描述與嚴格模式設定。伺服器端工具採用附有版本的官方定義。 |
tool_choice | object | auto（預設）或 none。any 與指定名稱的強制 tool 皆會遭到拒絕。auto 可包含 disable_parallel_tool_use。 |
metadata.user_id | string 或 null | 最多 512 個字元；請使用不透明識別碼。 |
cache_control | object 或 null | type: "ephemeral"；ttl: "5m"（預設）或 "1h"。Sonnet 5.5 至少需要 512 個可快取 token。官方 API 也支援內容區塊層級的快取中斷點。 |
diagnostics | object 或 null | previous_message_id：最多 256 個字元的字串，或 null。用於請求快取分歧診斷資訊。 |
service_tier | enum | auto（預設）或 standard_only。 |
speed | enum 或 null | 省略此項，或使用 standard / null。Sonnet 5.5 不支援 fast。 |
inference_geo | string 或 null | 官方預設值取自帳戶設定。請求獲得接受本身，無法驗證是否在指定地區處理。 |
fallbacks | string、object 陣列或 null，beta | "default" 或最多三個回退項目。每項必須包含 model；選填的覆寫項目為 max_tokens、thinking、output_config 與 speed。請參閱下文的回退規則。 |
fallback_credit_token | string、object 或 null | 先前拒絕回應提供的抵扣權杖，或 {"token":"...","mode":"strict"}。物件形式需要 fallback-credit-2026-07-01；mode 為 strict（預設）或 best_effort。不可與非 null 的 fallbacks 值同時使用。 |
container | string、object 或 null | 容器 ID，或含有選填 id 與 skills（最多 20 個）的容器設定。Skills 使用官方的型別、識別碼與版本欄位。 |
context_management | object 或 null | 官方的上下文編輯設定，包含 edits；null 表示省略此設定。仍須遵循模型專屬的編輯相容性要求。 |
mcp_servers | object 陣列 | 官方 MCP 伺服器定義，須符合所需的 beta 版本與伺服器驗證要求。空陣列測試無法驗證遠端 MCP 執行。 |
compaction | object 或 null，beta | {"type":"summarize"}，搭配 compact-2026-09-04；null 表示不啟用壓縮。啟用壓縮時，不可同時設定非 null 的 context_management、停止序列或結構化輸出格式。帶有簽章的壓縮行為未通過目前的測試。 |
messages[].output_config.effort | enum，beta | 在 system 訊息上設定個別訊息的投入程度；需要 mid-conversation-output-config-2026-07-01。只設定投入程度的 system 訊息可以出現在任何位置；包含內容的 system 訊息群組須遵循官方位置規則。在 between_tools 模式下，不得透過它變更投入程度。 |
between_tools 只接受自身的 type 屬性，投入程度僅限 low、medium 或 high。請勿搭配傳送 display、budget_tokens 或 block_binding。範例：
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"thinking": {"type": "between_tools"},
"output_config": {"effort": "medium"},
"messages": [{"role": "user", "content": "Explain this concept briefly."}]
}不支援 assistant 預填。若要繼續 pause_turn，請原樣回傳先前回應中的伺服器工具 assistant 內容。壓縮是將既有歷史記錄整理成摘要，不屬於 assistant 預填。請完整保留思考區塊與簽章；若未遵循官方綁定規則，請勿在模型之間搬移這些內容，也不要修改先前的歷史記錄。
在原生 Claude API 上，電腦使用功能需要 computer_toolset_20260801；computer_20251124 會遭到拒絕。此執行模型也會拒絕使用 claude-opus-4-8、claude-opus-4-7 或 claude-sonnet-5 的 Advisor 設定。
回退請求欄位
官方 fallbacks beta 功能會重試符合資格的分類器拒絕。它不會重試速率限制、過載或伺服器錯誤，而且重試後仍可能遭到拒絕。傳送 server-side-fallback-2026-07-01 標頭可使用 "default" 或明確清單；server-side-fallback-2026-06-01 僅支援清單。其他日期版本會遭到拒絕。
明確清單最多可包含三個項目，各模型必須互不相同，且都不能與請求的模型相同。允許的目標模型來自 beta Models API 的 allowed_fallback_models。每個項目只允許 model、max_tokens、thinking、output_config 與 speed；覆寫值必須適用於該目標模型。發生此類回退時，七月版 beta 會將 Sonnet 5.5 的 between_tools 轉換為 Sonnet 5 的 disabled，並省略 display。使用六月版 beta 時，必須自行提供 Sonnet 5 的思考設定覆寫值。
fallback_credit_token 用於遭拒後另行發起的重試。字串形式採用嚴格抵扣；物件形式則可指定 mode。在 strict 模式下，抵扣失敗會拒絕重試。在 best_effort 模式下，權杖層級的失敗可能允許請求按正常價格繼續，並記錄在 usage.fallback_credit 中；權杖格式錯誤，或將抵扣與 fallbacks 併用，仍會失敗。抵扣還須符合官方抵扣指南所列的請求資格、帳戶、工作區、平台及五分鐘期限。
一項無害請求使用 fallbacks: "default"、七月版 beta 標頭與 speed: "standard"，回傳了預期文字。這只能證明請求獲得接受：回退執行與抵扣兌換在此處尚未完成端到端驗證。
媒體與工具輸入
圖片使用使用者訊息中的 image 區塊，PDF 則使用 document 區塊。官方來源型別包含公開 URL，以及附有對應 MIME 型別的 base64。相容性檢查使用了 base64 PNG 與單頁 base64 PDF，並核對回答內容；並未測試所有 URL、檔案大小、圖片解析度或 PDF 頁數的邊界。
用戶端工具採用標準的 tool_use → tool_result 互動方式。請保留工具呼叫 ID，並以使用者訊息回傳結果。嚴格模式工具範例執行成功，只能驗證該範例的引數，無法驗證所有支援的 JSON Schema 關鍵字。
回應
非串流回應包含 id、type: "message"、role: "assistant"、model、content、stop_reason、stop_sequence 與 usage，以及選填的官方欄位，例如 container、diagnostics、context_management、stop_details 和 beta 回應欄位。內容可能包含文字、思考、工具呼叫、工具結果或其他官方區塊型別；請勿假定第一個區塊就是文字。
串流回應需要處理 message_start、content_block_start、content_block_delta、content_block_stop、message_delta 與 message_stop。串流內也可能發生錯誤。用量可能包含一般輸入/輸出 token、思考 token 明細、快取讀取，以及分別統計的 5 分鐘 / 1 小時快取寫入量。
官方分類器拒絕會以包含 stop_reason: "refusal" 與 stop_details 的正常回應傳回，而非 HTTP 錯誤。在回退回應中，model 指出實際作答的模型，fallback 內容區塊標記切換，usage.iterations 則描述各次嘗試。請檢查這些欄位，而不是假定回應由請求中指定的模型提供。這些回應行為在此處仍未經驗證。
Messages 錯誤採用 {"type":"error","error":{"type":"...","message":"..."}} 格式。失敗的請求不收費。
相容性驗證：2026-10-01
| 結果 | 已檢查的行為 |
|---|---|
| 觀察到可正常運作 | 基本文字、一般多輪對話的內容回憶、不衝突的字串/區塊形式系統指令、串流、自適應與工具呼叫之間的思考請求、JSON 輸出、auto/none 工具、一項嚴格模式工具呼叫、工具結果回傳、base64 圖片/PDF 輸入，以及 5m/1h 快取寫入/讀取用量。 |
| 依模型規範拒絕 | 無效的輸出 token 預算、已移除的取樣設定、手動/停用思考、無效的 between-tools 組合、強制工具呼叫、assistant 預填、舊版電腦工具，以及過長的 metadata ID。 |
| 請求獲得接受，效果尚未證實 | 全部五種投入程度、思考摘要、綁定設定、metadata、服務層級、地區選擇、診斷、空的上下文編輯清單、null 容器、空的 MCP 清單與電腦工具集宣告。宣告工具集不代表電腦使用功能執行成功。 |
| 已知不一致 | max_tokens: 0 回傳 400。停止序列請求回傳了停止字串及其後續文字。隨需壓縮回傳的是一般文字，而非帶有簽章的壓縮區塊。 |
| 仍需調查的其他行為 | 一項設定個別訊息投入程度的請求未能回憶先前的值；一項系統/使用者指令衝突測試遵循了使用者指令。這些結果無法證明所有系統提示或多輪請求都會失敗。 |
Beta 工具執行、實際 MCP 連線、Files API 參照、資料駐留地區、思考簽章回傳、完整上下文/輸出上限、媒體邊界情況，以及拒絕/回退行為，皆尚未完成端到端驗證。HTTP 200 與回傳的模型名稱無法證實實際執行的是哪個模型，也無法證明傳入的所有選項均已生效。