Claude API 2026-10-21 更新：三年來首個新版本改了什麼

Anthropic 在十月二十一日發布 Claude API 版本 2026-10-21，這是自二〇二三年六月一日以來第一個新版本。同一天，八個 SDK 與 ant CLI 一起升上主版本號。

更新幅度不小，方向也明確：拿掉取樣參數、收緊兩種訊息結構、改了管理介面的欄位名，還把金鑰改用不同的標頭送出。這是 Claude API 破壞性變更最集中的一次，舊教學有一半會失效。這篇按「會壞在哪裡」的順序講。

Claude API 2026-10-21 是三年來第一個新版本

版本號放在請求的 anthropic-version 標頭裡。問題在於 SDK 會記住自己出生時的版本：你升了套件但沒升主版本，請求仍然寫著2023-06-01，程式看起來一切正常。

所以第一個判斷是：這次升級不是「換個號碼」，是換一組規則。舊版仍在運作，官方也沒有公布2023-06-01 的終止日期，但新建議一律用新版本。

三個取樣參數被移除，送了就回 400

temperature、top_p、top_k 在新版本直接被移除。就算你送的是預設值，一樣會收到 400。Message Batches 與 token 計數端點同樣適用。

新的 SDK 主版本裡已經沒有這三個參數，刪掉就能跑。不送的請求會用預設值取樣，也就是 temperature 1.0，跟舊版什麼都不填的結果一致。

真正的損失落在需要降溫的場景。Claude 4.7 之後的模型本來只接受預設值，改動對它們沒有影響；Claude Sonnet 4.6 這類仍接受其他值的模型，過去靠低 temperature 換取穩定輸出的做法沒有了，官方文件寫得很直接：「沒有其他設定可以取代它」。

如果你的服務正是靠這個手段壓住輸出格式，留在2023-06-01 是合理選擇。

另外兩種會被拒絕的訊息結構

除了參數，還有兩種訊息寫法會回 400。

第一種是把文件區塊直接放進 assistant 訊息。文件要放在 user 訊息裡送。

第二種是 user 訊息裡的文字區塊帶著非空的 citations 陣列，包括放在 search_result 裡的情況。Claude 自己回覆時附上的 citations，你原樣送回去仍然接受，這點不用改。

Admin API 欄位改名，儀表板要跟著修

管理介面的欄位換了名字，靠舊欄位搭的監控看板會先壞：

• API key 項目不再回傳 workspace_id，改用 scope.workspace_id
• RBAC 角色回傳 display_name，不再是 name
• 速率限制項目回傳 group.type，不再是 group_type
• Enterprise Analytics 報告的 actor.email 改成 actor.email_address

Claude SDK 2.0 與各語言版本清單

八個套件同時升主版本，而且授權從 MIT 改成 Apache 2.0：

Python 這一側還有三個容易踩的地方：MessageParam 型別變成 UserMessageParam、AssistantMessageParam 與 SystemMessageParam 的聯合型別，直接呼叫 MessageParam(role="user", content="Hello") 會拋 TypeError，改用字典；client.models.list() 與 retrieve() 不再吃 betas 參數，要改走 client.beta.models.list；一個 client 只帶一組憑證，同時給 api_key 與 auth_token 會拋 ValueError。

金鑰改走 Authorization: Bearer，代理與閘道要跟著改

新的 SDK 把 API 金鑰放在 Authorization: Bearer，不再送 X-Api-Key。Claude API 本身兩種標頭都收，所以直連的程式沒事。

出問題的是中間那層。公司自建的閘道、記錄日誌的代理、負責路由的服務，如果只認 X-Api-Key，升級之後會看到一個沒有金鑰的請求。解法有兩個：改讀 Authorization，或者在 HTTP client 上把 X-Api-Key 補回去。

憑證的尋找順序也變了：程式沒給憑證時，client 依序看 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_PROFILE 指到的設定、workload identity federation 的變數，最後才是磁碟上的設定檔。前兩者同時存在時會留一行警告。

Claude API 遷移的實際步驟

官方建議在同一個版本內完成升級、修正與上線，不要分兩次。實作上按這個順序走：

1. 全專案搜尋 temperature、top_p、top_k，包括 Message Batch 任務與會把參數往下傳的提示詞模板
2. 檢查所有讀 X-Api-Key 的代理、閘道與測試替身
3. 升級套件，例如安裝 anthropic>=2.0.0，然後跑型別檢查，處理 MessageParam 與 betas 的錯誤
4. 在 Bedrock 上跑舊模型的服務先別升，留在現行版本
5. 用新版本跑一輪整合測試，確認計費與日誌沒有斷

Claude Code 2.1.307 在同一天加了 /claude-api api-version 指令，用來把 API 程式碼推到新版本。官方沒有說明它實際改了哪些檔案，跑完之後還是要自己看 diff。

哪些情況下應該留在 2023-06-01

三種情況值得暫緩：服務依賴非預設的 temperature；在 Bedrock 上呼叫 Claude 4.7 之前的模型；關鍵第三方工具還沒跟上新標頭。

留在舊版不是長久方案，只是給自己一段時間。真正的風險是那條看起來無害的呼叫：把 temperature 設成預設值，讀起來像沒做任何事，在新版本卻一樣失敗。這種錯最容易被跳過，也最常在正式環境才被抓到。

結論

這次更新的核心不是新功能，是把過去三年累積的彈性收掉。取樣參數、寬鬆的訊息結構、舊的認證標頭，三樣一起退場。

對多數團隊來說，值得升，但要當成一次真正的遷移來做：先搜參數，再查代理，然後一次改完、一次上線。想先看規格細節，官方遷移文件寫得比發佈公告清楚。