Claude API 2026-10-21 版本：改了什么，以及如何安全升级

Claude API 版本 2026-10-21 是自 2023-06-01 以来第一个新的 anthropic-version 值。它对 Messages API 做了三项破坏性变更：temperature、top_p 和 top_k 返回 400；assistant 消息中的 document 块返回 400；user 消息中 text 块上的 citations 返回 400。它还重命名了若干 Admin API 和 Enterprise Analytics API 字段。发送 anthropic-version: 2026-10-21 或升级到新 SDK 主版本（Python 2.0.0、TypeScript 1.0.0、Go 2.0.0 等）即可选择启用。

问题在于：升级 SDK 正是大多数团队会“意外”迁移的方式。一次跨主版本的 pip install -U anthropic 或 npm update 会让所有请求一次性切到 2026-10-21。本文列出所有变更、哪些会在真实代码中造成影响，并给出安全升级顺序。

什么是 anthropic-version？

anthropic-version 是必需请求头，用于固定 Claude API 的形态。同一版本内，现有输入输出参数保持稳定，但可能增加可选输入、新输出值、新枚举（如流式事件类型）和新错误条件。破坏性变更只随新版本日期到来。

根据版本管理页：

使用官方 SDK 时无需自己设置请求头；每个主版本发送发布时的当前版本。因此 SDK 升级和 API 版本升级对大多数代码库是同一件事。

2026-10-21 的破坏性变更

适用于 POST /v1/messages、token 计数，以及使用 2026-10-21 创建的 Message Batch 中的每个请求。

1. temperature、top_p、top_k 被移除

任何发送这些参数的请求都会在所有模型上返回 400，即使发送默认值。配置文件残留 temperature: 1.0 就足以让调用失败。

输出质量影响取决于模型：

• Claude 4.7 及更高版本只接受默认采样值，移除参数不改变采样方式。
• 接受其他值的旧模型，如 Claude Sonnet 4.6，会失去降低 temperature 的效果。迁移指南明确：没有其他设置可替代。

如果请求确实依赖非默认值，只能停止发送，或让该请求继续使用 2023-06-01。

2. assistant 消息中的 document 返回 400

一些应用在重放历史时把 document 直接放在 assistant 轮次，2026-10-21 会拒绝。请移到 user 消息。嵌套在其他块中的文档（如 web fetch 工具结果）仍接受。

3. user 消息中的 citations 返回 400

user 消息中带非空 citations 数组的 text 块会失败，包括 search_result 内的文本。请移除 citations。Claude 自己 assistant 回复上的 citations 仍可回传，文档和搜索结果上的 "citations": {"enabled": true} 也没问题。

4. Admin API 和 Analytics 字段重命名

API 密钥变更较微妙。2023-06-01 下，Default Workspace 密钥和全工作区密钥的 workspace_id 都是 null；2026-10-21 下，scope.workspace_id 保存 Default Workspace 真实 ID，全工作区密钥的 scope 为 {"type": "organization"}，没有 workspace_id。如果仪表盘把 null 当“Default Workspace”，升级后会标错。

默认发送 2026-10-21 的 SDK

根据发布说明：

新主版本还带来与 API 版本无关的变更：

• API 密钥以 Authorization: Bearer <key> 发送，而不是 X-Api-Key。API 两者都接受，但读取 X-Api-Key 的代理、网关、日志过滤器或测试桩将看不到密钥。
• Text Completions 从 TypeScript、Go、Java、Ruby SDK 和 CLI 移除。 请用 Messages API。
• 非 beta Models 方法中的 betas 移除。 改为 client.beta.models。
• 类型化 SDK 中 MessageParam 是按角色区分的联合类型，部分类型注解需更新。
• Go 需要以 /v2 结尾的新导入路径；Bedrock、Vertex、Foundry、AWS 或 Google Cloud 包的 TypeScript 用户必须同时移到 v1，否则会安装旧的核心 SDK。
• 许可证从 MIT 改为 Apache 2.0。

先锁定当前主版本，阻止依赖机器人中途升级。

Amazon Bedrock 例外

Bedrock 上 2026-10-21 仅适用于 Claude 4.7 及更高版本。调用 Opus 4.6 或更旧模型时，请保持当前 SDK 或请求头，并先切换模型。

安全升级顺序

迁移指南顺序：切换版本、修复变更、发布前测试。实际做法：

1. 锁定旧 SDK 主版本。 如 Python anthropic<2，npm "@anthropic-ai/sdk": "^0"。
2. 搜索代码和配置中的 temperature、top_p、top_k、X-Api-Key、completions.create 及上表 Admin 字段。
3. 决定采样。 Claude 4.7+ 删除参数；旧模型接受默认采样，或保留在 2023-06-01。
4. 修复消息构造。 assistant 侧文档移到 user 轮次，移除 user 文本块中的 citations。
5. 两个版本测试相同 payload，比较状态码和响应结构。
6. 一起发布 SDK 升级和修复。 不要先发布升级。

不用 SDK 时，切换只需一个请求头：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

加入 "temperature": 0.2 会得到 400；用 anthropic-version: 2023-06-01 发送同一请求体则成功。这对结果是第 5 步应为每个生产 payload 捕获的。

让 Claude Code 用 Apifox CLI 测试两个版本

第 5 步手动做很乏味：几十种 payload，每种运行两次。交给编码 Agent。Apifox CLI 提供创建和运行测试用例的命令。

先配置：

npm install -g apifox-cli@latest
apifox login --with-token <YOUR_TOKEN>
npx -y skills add https://apifox.com   # 按提示选择 Claude Code

给 Claude Code 一段提示：

In Apifox project <id>, create an environment "claude-api" with base URL
https://api.anthropic.com. For each JSON payload in ./fixtures/claude/, add a
POST /v1/messages test case that sends the header anthropic-version: {{anthropic_version}}
and asserts status 200 and a non-empty content array. Run every case twice, once with
anthropic_version=2023-06-01 and once with 2026-10-21, and list each case that passes
on the old version but fails on the new one, with the error message.

Agent 先检查 payload schema，再运行：

apifox environment create claude-api --project <id> --base-url https://api.anthropic.com
apifox cli-schema get test-case-create
apifox cli-schema validate test-case-create --file case.json
apifox test-case create --project <id> --file case.json
apifox run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2023-06-01" -r cli,json
apifox run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2026-10-21" -r cli,json

--env-var 在不改测试用例的情况下切换请求头，差异只是一个变量。添加 --upload-report 可在 Apifox 应用查看两次运行，或用 -r junit 把新版本运行放进 CI，防止依赖升级把 temperature 带到生产。Claude Code 中的 Apifox CLI 指南有详细配置，apifox run 参考列出所有标志。

2023-06-01 被弃用了吗？

没有公布退役日期。版本页没有弃用通知，迁移指南建议把需要非默认 temperature 的请求保留在 2023-06-01。Anthropic 仍推荐“尽可能”使用最新版本。

今天的升级可选，但 2026-10-21 是三年多来第一个新版本，未来破坏性变更也会同样到来。现在把版本测试当作例行 CI，比以后匆忙迁移便宜。如果你已在调优 Claude API 速率限制或成本，请把版本检查加入同一流水线。API 版本管理最佳实践解释了日期版本的好处。

常见问题

现在必须升级吗？ 不必。2023-06-01 仍可用，没有退役日期。只有发送新请求头或安装默认新版本的 SDK 主版本时才升级。

为什么 SDK 升级后返回 400？ 新主版本发送 2026-10-21，拒绝 temperature、top_p、top_k、assistant 侧 document 和 user 文本块上的 citations。先检查 payload。

可以保留部分请求的 temperature 吗？ 可以，让那些请求继续使用 2023-06-01。新版本没有替代设置，Claude 4.7+ 本来就只用默认值采样。

2026-10-21 在 Bedrock 上可用吗？ 仅 Claude 4.7 及更高版本。旧 Bedrock 模型需保持当前 SDK 或请求头，直到切换模型。

代理还能看到 API 密钥吗？ 如果读取 X-Api-Key 就看不到。新 SDK 用 Authorization: Bearer。请更新代理读取 Authorization，或配置 SDK 发送 X-Api-Key。

流式事件变了吗？ 没有列出格式变更。今天的流式格式来自 2023-06-01。