升級到 Anthropic API 版本 2026-10-21 之後,為什麼請求裡還帶著 temperature 就會直接 400?

截至 2026 年 10 月 26 日:2026-10-21 拒絕 Messages 中的 temperature、top_p、top_k(含預設值)。Python SDK 2.0 預設發送該版本。另需處理 document、citations 與 Admin 回應欄位改名。

先給結論:2026-10-21 會把 Messages 請求裡出現的 temperature、top_p、top_k 一律當成非法欄位,哪怕你傳的是檔案裡的預設值也會 400。Python SDK 2.0、TypeScript SDK 1.0 和 ant CLI 2.0 預設就帶 anthropic-version: 2026-10-21。升級主版本後,舊請求體裡若還留著這三個鍵,失敗點往往在 JSON 校驗之前。同一天發布的使用者檔案介面還多了 enforcement_status 與 enforcement_actions,Admin API 若干響應欄位也改名,解析指令碼要一起改。

這篇按 2026 年 10 月 26 日寫,依據 10 月 21 日的遷移指南與版本說明。前天本站寫過《OpenAI Decisions API 的 answers JSON》。那邊是固定答案形狀;這邊是 Messages 請求體與 Admin 響應體的破壞性欄位變更。

什麼時候會悄悄切到 2026-10-21

遷移指南寫明:SDK 主版本發布時繫結的 API 版本會隨請求自動傳送。升到 Python anthropic 2.0.0、TypeScript @anthropic-ai/sdk 1.0.0、Go anthropic-sdk-go/v2 2.0.0 等,就不必再手寫版本頭也會走 2026-10-21。裸 HTTP 呼叫則要顯式設 anthropic-version: 2026-10-21。

Amazon Bedrock 上,2026-10-21 僅適用於 Claude 4.7 及以後模型;Opus 4.6 及更早型號若強行升 SDK 卻未換模型,仍應留在舊 SDK 或舊版本頭。Google Cloud、Foundry 與直連 Claude API 的適用範圍以官方版本頁為準。

三個取樣欄位為什麼必須刪掉

在 2023-06-01 上,省略 temperature 等價於預設 1.0。在 2026-10-21 上,出現鍵名即錯誤,不是值不對才報錯。配置中心、特性開關或 ORM 若預設注入 "temperature": 0,升級當天就會全量 400。

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Summarize this ticket."}]
}

Claude 4.7 及以後本來就只接受預設取樣,刪掉欄位後行為與以前「不傳」一致。若你還在 Claude Sonnet 4.6 等老型號上靠 temperature: 0.2 壓隨機性,遷移指南寫明沒有替代參數:要麼接受預設 1.0,要麼該條請求繼續用 2023-06-01。Message Batch 裡每條子請求同樣適用。

Messages 裡另外兩處 400

除取樣欄位外,2026-10-21 還收緊了兩類 content block:

  • assistant 訊息裡的 document:不能把 document 塊直接放在 role: assistant 下;應放在 user 訊息,或保留嵌在 tool 結果裡的 document。
  • user 訊息裡帶 citations 的 text:user 角色下 text 塊的 citations 陣列不能為空;assistant 側回傳的引用文字仍允許。文件級 "citations": {"enabled": true} 不受影響。

多輪 Agent 把搜尋結果塞回上下文時,最容易踩第二條:把帶 citations 的 user 塊原樣 replay,會在新版本下 400。

Admin 響應 JSON 欄位改名

若你的運維指令碼解析 Admin API 或 Enterprise Analytics 響應,2026-10-21 起舊欄位名不再出現,需要改 JSONPath 或型別定義:

場景舊欄位新欄位
RBAC 組rolesrole_ids
組成員group_idrbac_group_id
RBAC 角色namedisplay_name
速率限制group_typegroup.type
API 金鑰workspace_idscope.workspace_id 或組織級 scope.type
分析:使用者報表actor.emailactor.email_address
活動摘要summariesdata

API 金鑰尤其容易誤判:以前 workspace_id: null 可能表示 Default Workspace;現在應讀 scope,全組織金鑰是 {"type": "organization"},繫結工作區時 scope.workspace_id 為真實 ID。列表過濾參數 workspace_id 查詢串未改,變的是響應體形狀。

user profiles 與 enforcement 欄位

10 月 21 日發行說明還加了使用者檔案上的 enforcement_status 與 enforcement_actions,用於判斷終端使用者是否被限制或封禁。列表介面可用 enforcement_status[] 過濾。這與版本頭無直接關係,但常與 SDK 2.0 同一週上線;合規流水線應把這兩項和 Messages 升級一起測。

升級時要留的請求快照

灰度時至少記錄:

{
  "anthropic_version": "2026-10-21",
  "sdk": "anthropic-python-2.0.0",
  "model": "claude-sonnet-5-5",
  "request_keys": ["model", "max_tokens", "messages", "system"],
  "has_temperature": false,
  "has_top_p": false,
  "has_top_k": false,
  "http_status": 200
}
  • JSON 校驗 — 確認出站 Messages 體裡沒有那三個取樣鍵。
  • JSON Diff — 對比升級前後 Admin 列表響應的欄位名。
  • JSONPath — 例如從金鑰列表取 $.data[*].scope.workspace_id。

常見問題 FAQ

只升級 SDK、請求 JSON 沒改,也會 400 嗎?

會,只要請求體仍含 temperature、top_p 或 top_k 任一鍵。新版本 API 不認這些欄位,與 SDK 是否已刪型別無關。要從序列化層或中介軟體去掉鍵名。

傳 temperature 1.0 算不算預設值可以保留?

不算。遷移指南寫明即使等於預設值也返回 400。必須整鍵刪除,不能改成 1.0 繼續傳。

Message Batch 的子請求也要刪嗎?

要。用 2026-10-21 建立的批次裡,每條子請求遵守同一套 Messages 規則,包括取樣欄位與 document、citations 限制。

Bedrock 上的 Opus 4.6 能直接升 SDK 2.0 嗎?

遷移指南建議 Opus 4.6 及更早 Bedrock 型號繼續用舊 SDK 或舊版本頭,或先換 Claude 4.7+ 再切 2026-10-21。否則版本與模型能力不匹配。

Admin 列表還能用 workspace_id 過濾嗎?

查詢參數 workspace_id 未改。變的是響應裡 API 金鑰物件不再頂層返回 workspace_id,應解析 scope。

enforcement_status 必須設 2026-10-21 才有嗎?

使用者檔案欄位隨 10 月 21 日平臺更新發布,與 Messages 破壞性變更同一波檔案。整合時應確認你用的 Admin 或 Profile 端點版本與欄位說明一致。

總結

2026-10-21 的核心是「欄位不存在」而不是「值非法」。刪掉 temperature、top_p、top_k;檢查 assistant document 與 user citations;Admin 與 Analytics 響應改讀新鍵名。SDK 主版本升級和請求體清理應同一次發布。