遷移至 API 版本 2026-10-21

本指南列出從 API 版本 2023-06-01 遷移至 2026-10-21 所需的程式碼變更。升級步驟依序說明您需要執行的操作。

升級步驟

1. 1

   切換至 2026-10-21

   如果您使用 SDK，您的請求會使用該 SDK 主要版本發布時的現行 API 版本。下方針對您的語言所列出的版本，是第一個使用 2026-10-21 的版本，因此請升級至這些版本。如果您不透過 SDK 呼叫 API，請將 anthropic-version 標頭設定為 2026-10-21。

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   將 anthropic 套件升級至 2.0.0 版。

   請將此升級與下一步驟中的修正一併發布。

2. 2

   針對重大變更更新您的程式碼

   逐一檢視重大變更，並針對每一項會影響您的變更更新程式碼。同時也請進行新版 SDK 或 CLI 所需的程式碼變更。

3. 3

   針對 2026-10-21 進行測試

   在發布之前，請針對 2026-10-21 測試您的整合。

重大變更

Messages API

這些變更適用於對 Messages API（POST /v1/messages）的請求、token 計數，以及以 2026-10-21 建立的 Message Batch 中的每個請求。

assistant 訊息中的 document 區塊會傳回錯誤

如果您直接在 assistant 訊息中傳送 document 區塊，則會受到影響。

在 2026-10-21 中，直接在 assistant 訊息中放置 document 區塊的請求會傳回 400 錯誤。請改為在 user 訊息中傳送文件。巢狀於其他區塊中的文件（例如 Claude 傳回的網頁擷取工具結果）仍會被接受。

user 訊息中的引用會傳回錯誤

如果您在 user 訊息的 text 區塊上傳送 citations（包括在 search_result 區塊內），則會受到影響。

在 2026-10-21 中，在 user 訊息中傳送帶有非空 citations 陣列之 text 區塊的請求會傳回 400 錯誤。請從這些區塊中移除 citations。assistant 訊息中 text 區塊上的引用（例如您回傳的 Claude 先前回覆）仍會被接受，文件與搜尋結果上的 "citations": {"enabled": true} 設定也同樣會被接受。

取樣參數已移除

如果您在 Messages 請求或 Message Batch 請求中傳送 temperature、top_p 或 top_k，則會受到影響。

在 2026-10-21 中，傳送 temperature、top_p 或 top_k 的請求會傳回 400 錯誤，即使參數值為預設值也是如此。

請從您的請求中移除這三個參數。

自最新的主要版本起，SDK 與 CLI 已不再提供這三個參數。

沒有這些參數時，請求會以其預設值進行取樣，包括 temperature 為 1.0，與省略這些參數的 2023-06-01 請求相同。已經只接受預設值的模型（例如 Claude 4.7 及更新的模型）會與先前一樣進行取樣。在接受其他值的模型上（例如 Claude Sonnet 4.6），原本為了獲得更一致的輸出而調低 temperature 的請求將失去該效果，且沒有其他設定可以取代它。如果某個請求依賴非預設值，請停止傳送該參數，或讓該請求繼續使用 2023-06-01。

Admin API 與 Claude Enterprise Analytics API

如果您的程式碼讀取下表中的 Admin API 或 Claude Enterprise Analytics API 回應欄位，則會受到影響。

在 2026-10-21 中，Admin API 與 Claude Enterprise Analytics API 的回應不再包含已重新命名欄位的舊名稱。請改用新名稱。

Admin API：

Claude Enterprise Analytics API：

速率限制列出端點上的 group_type 查詢參數，以及 API 金鑰列出端點上的 workspace_id 篩選條件維持不變。

API 金鑰上的 workspace_id

如果您的程式碼讀取 API 金鑰上的 workspace_id，則會受到影響。

在 2023-06-01 中，API 金鑰的 workspace_id 是該金鑰所綁定之工作區的 ID；對於綁定至 Default Workspace 的金鑰，以及未綁定至單一工作區的金鑰（全工作區金鑰），其值為 null。

在 2026-10-21 中，workspace_id 已移除。請改為讀取 scope：對於綁定至某個工作區（包括 Default Workspace）的金鑰，scope.workspace_id 是該工作區的實際 ID；而全工作區金鑰的 scope 為 {"type": "organization"}，且沒有 workspace_id。

如果您的程式碼將 null 的 workspace_id 視為 Default Workspace，請改為將 scope.workspace_id 與您的 Default Workspace ID 進行比較。若要找出該 ID，請以 include_default=true 呼叫 List Workspaces，並取得名稱為 "Default" 的工作區。

SDK 與 CLI 變更

較早的 SDK 與 CLI 版本會在每個請求中傳送 anthropic-version: 2023-06-01。切換至 2026-10-21 中所列的版本則會傳送 2026-10-21。重大變更中的變更同樣適用於這些版本：已移除的參數與舊欄位名稱也已從 SDK 的型別以及 CLI 的旗標與輸出中移除。

Amazon Bedrock 與 Google Cloud 上的 API 版本

SDK 中用於 Google Cloud's Agent Platform 的用戶端會在請求主體中指定版本，而非在標頭中。它會傳送 anthropic_version: 2026-10-21（較早的版本傳送的是 vertex-2023-10-16），且不傳送 anthropic-version 標頭。

Amazon Bedrock 用戶端也是如此。它會傳送 anthropic_version: 2026-10-21（較早的版本傳送的是 bedrock-2023-05-31），且不傳送 anthropic-version 標頭。早於 Claude Opus 4.7 的模型目前尚不支援 Bedrock 上的 API 版本 2026-10-21，指定該版本的請求可能會收到 400 錯誤。如果您使用其中任何一個模型，請暫時繼續使用較早的 SDK 版本，或者升級後自行傳送 bedrock-2023-05-31。

MessageParam 是每個角色各有一個型別的 union

在較早的版本中，MessageParam 是適用於所有角色的單一型別。現在每個角色都有自己的型別：UserMessageParam、AssistantMessageParam 與 SystemMessageParam。BetaMessageParam 也以相同方式拆分為 BetaUserMessageParam、BetaAssistantMessageParam 與 BetaSystemMessageParam。SDK 傳送的請求具有與先前相同的欄位與值。

# 之前
message = MessageParam(role="user", content="Hello")

# 之後
message: MessageParam = {"role": "user", "content": "Hello"}

# 之前
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    return {"role": role, "content": text}


# 之後
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    if role == "user":
        return {"role": "user", "content": text}
    return {"role": "assistant", "content": text}

單一值列舉現在是常數

這會影響 C#、Go、Java、PHP 和 Ruby SDK，以及一個 CLI 旗標。在較早的版本中，只能容納一個值的必要欄位擁有自己的列舉型別，且該列舉只有一個成員。這些欄位現在是常數，而這些列舉型別已被移除。SDK 傳送和讀取的 JSON 保持不變。

已從 tool runner 中移除用戶端壓縮

這會影響 TypeScript 和 Ruby SDK。tool runner 中的「client-side compaction」（用戶端壓縮）已被移除，改用伺服器端壓縮，後者會在 API 內部摘要對話，而不是由用戶端發出額外的請求。

// 之前
const runner = client.beta.messages.toolRunner({
  // ...
  compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});

// 之後
const runner = client.beta.messages.toolRunner({
  // ...
  betas: ["compact-2026-01-12"],
  context_management: {
    edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
  }
});

觸發閾值必須至少為 50,000 個 token。如需其他選項（pause_after_compaction、自訂 instructions），請參閱壓縮。

Text Completions 已被移除

舊版 Text Completions API 已從 TypeScript、Go、Java 和 Ruby SDK 以及 CLI 中移除。較新的模型和功能不支援它。請改用 Messages API。

# 之前
ant completions create \
  --model "$MODEL" \
  --max-tokens-to-sample 1024 \
  --prompt $'\n\nHuman: Hello, Claude\n\nAssistant:'

# 之後
ant messages create \
  --model "$MODEL" \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

已從非 beta 的 Models 方法中移除 betas

非 beta 的 Models 方法不再接受 betas，而 ant models 命令也不再接受 --beta。若要傳送 beta 標頭，請在 client.beta.models 上呼叫相同的方法，或在 CLI 中使用 ant beta:models。在 SDK 中，這些方法會傳回 BetaModelInfo，而非 beta 的方法則傳回 ModelInfo。

# 之前
page = client.models.list(betas=[beta])

# 之後
page = client.beta.models.list(betas=[beta])

API 金鑰以 Authorization: Bearer 傳送

SDK 和 CLI 會以 Authorization: Bearer <key> 傳送您的 API 金鑰，而不是放在 X-Api-Key 標頭中，因此請將任何讀取或設定 X-Api-Key 的代理或閘道改為使用 Authorization，或自行在 X-Api-Key 中傳送金鑰。Claude API 接受放在任一標頭中的金鑰，因此直接與 API 通訊的程式無需變更。

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

如果代理或閘道讀取 X-Api-Key

import httpx2
from anthropic import Anthropic, DefaultHttpxClient


def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request


client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))

如果您曾在請求上設定或移除 X-Api-Key

這會影響 Python、TypeScript、Go、PHP 和 Ruby SDK。

如果您曾移除 X-Api-Key 以讓請求只傳送 auth token，請刪除該程式碼而不是修改它，因為移除 Authorization 會移除該 token。一個用戶端只持有一個憑證，因此請確保該憑證是 token：如果程式碼中未傳入任何憑證，且同時設定了 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN，用戶端會使用金鑰。

用戶端只持有一個憑證

API 金鑰與驗證權杖現在共用同一個標頭，因此 SDK 用戶端只持有一個憑證。若未在程式碼中傳入任何憑證，則會依照憑證優先順序的順序處理。

client = Anthropic(api_key=key, auth_token=token)

# 之前：會傳送 `X-Api-Key: <key>` 與 `Authorization: Bearer <token>`
# 之後：引發 `ValueError`

單一 SDK 或 CLI 中的變更

以下每項變更各自只影響一個 SDK 或 CLI。

# 修改前
ant --api-key "$KEY" models list

# 修改後，從環境變數讀取
export ANTHROPIC_API_KEY="$KEY"
ant models list

# 修改後，從密鑰管理工具讀取
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

授權條款為 Apache 2.0

從這些版本開始，SDK 與 CLI 採用 Apache License, Version 2.0 授權。較早的版本仍維持 MIT License。不需要變更任何程式碼。如果您有追蹤相依套件的授權條款，請更新其項目。

• TypeScript： 平台套件（@anthropic-ai/bedrock-sdk、@anthropic-ai/vertex-sdk、@anthropic-ai/foundry-sdk、@anthropic-ai/aws-sdk 與 @anthropic-ai/google-cloud-sdk）會在各自的 1.0.0 版本中變更授權條款。
• C#： 其他套件（Anthropic.Bedrock、Anthropic.Vertex、Anthropic.Foundry、Anthropic.Aws、Anthropic.GoogleCloud 與 Anthropic.Mcp）會在各自的 1.0.0 版本中變更授權條款。
• Java： 此變更涵蓋所有 com.anthropic 構件。