迁移到 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

   针对破坏性变更更新您的代码

   逐一查看 breaking changes（破坏性变更），并针对每一项影响您的变更更新代码。同时完成新版 SDK 或 CLI 所需的代码更改。

3. 3

   针对 2026-10-21 进行测试

   在发布之前，针对 2026-10-21 测试您的集成。

破坏性变更

Messages API

这些变更适用于对 Messages API（POST /v1/messages）的请求、令牌计数，以及使用 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 是每个角色对应一种类型的联合类型

在早期版本中，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 保持不变。

工具运行器中的客户端压缩已被移除

此变更影响 TypeScript 和 Ruby SDK。工具运行器（tool runner）中的客户端压缩已被移除，改用服务器端压缩。服务器端压缩在 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 个令牌。有关其他选项（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"}'

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

非 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 是为了让请求只发送认证令牌，请删除该代码而不是修改它，因为移除 Authorization 会移除该令牌。一个客户端只持有一个凭据，因此请确保该凭据是令牌：如果代码中未传入任何凭据，且同时设置了 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN，客户端会使用密钥。

客户端只持有一个凭据

API 密钥和 auth token（身份验证令牌）现在共用一个标头，因此 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 构件。