Claude API 三年来第一个正式新版本：temperature/top_p/top_k 被删，迁移清单来了

2026 年 10 月 21 日，Anthropic 发布了 Claude API 的新版本 2026-10-21。这件事值得专门写一篇文章，原因很简单：上一个正式版本 2023-06-01 发布于 2023 年 6 月——整整三年多，Claude API 的版本号第一次动了。与此同时，七个语言的官方 SDK 全部跳了大版本（Python 2.0.0、TypeScript 1.0.0、C# 13.0.0、Go 2.0.0、Java 3.0.0、PHP 1.0.0、Ruby 2.0.0），ant 命令行工具也来到了 2.0.0，新版本 SDK 和 CLI 默认发送的就是 2026-10-21。

版本号一动，必然有破坏性变更。这次最抓眼球的一条是：Messages API 里 temperature、top_p、top_k 三个采样参数被彻底删掉了——发送即返回 400 错误，哪怕你传的是默认值。除此之外，Admin API 一批字段改名、SDK 改用 Authorization: Bearer 鉴权头、许可证从 MIT 换成 Apache 2.0，还有几处容易踩坑的细节。本文把官方迁移指南逐条拆开，告诉你谁会被影响、谁可以不动，以及一份可以直接照着执行的迁移清单。

先看核心变化一览

变化	详情
新 API 版本	2026-10-21，2023 年 6 月以来首个正式版本；旧版 2023-06-01 暂不弃用
新 SDK（默认发送新版本）	Python 2.0.0、TypeScript 1.0.0、C# 13.0.0、Go 2.0.0、Java 3.0.0、PHP 1.0.0、Ruby 2.0.0，ant CLI 2.0.0
最受关注的破坏性变更	Messages API 移除 temperature、top_p、top_k，发送即 400
其他请求层变更	assistant 消息直接放 document 块 400；user 消息 text 块带非空 citations 数组 400
管理面变更	Admin API 与 Enterprise Analytics API 一批字段改名（如 roles→role_ids）
SDK 独立变更	鉴权头改 Authorization: Bearer；TS/Go/Java/Ruby 移除 Text Completions；TS/Ruby 移除客户端 compaction
许可证	新版 SDK 与 CLI 从 MIT 换为 Apache 2.0，无需代码变更

破坏性变更逐条拆解

1. 采样三参数被删：temperature、top_p、top_k

这是整份迁移指南里杀伤力最大的一条。在 2026-10-21 下，任何 Messages API 请求（包括 token counting 和 Message Batch 里的每一条请求）只要带了 temperature、top_p、top_k 中的任意一个，就会直接返回 400——即使传的是默认值也一样。官方的原话是 "even at the parameter's default value"，没有例外，没有宽限。

删掉参数之后，请求按默认值采样，等价于以前不传这三个参数的请求，也就是 temperature=1.0 的效果。这里有一个关键的分水岭：Claude 4.7 及更新的模型本来就只接受默认值，所以对它们来说行为没有任何变化；但像 Claude Sonnet 4.6 这样还接受非默认值的模型，如果你之前靠调低 temperature 来让输出更稳定，升级后这个效果就没了——官方明确说 "No other setting replaces it"，没有其他设置可以替代。

官方给了两条出路：要么删掉参数接受默认采样，要么把依赖非默认值的请求继续留在 2023-06-01 上。值得注意的是，这并不是 Anthropic 第一次动手：10 月 7 日发布的 Claude Haiku 5.5 迁移指南里就写过，采样参数和 assistant prefill 在新模型上同样会 400。方向很清楚——Anthropic 正在系统性地收回开发者对采样过程的控制权。

2. assistant 消息里直接放 document 块：400

如果你在构造多轮对话时，把 document 块直接塞进 assistant 消息里，新版本会返回 400。正确做法是把文档放在 user 消息里。一个例外：文档嵌在别的块内部仍然被接受，比如 Claude 之前返回的 web fetch 工具结果里自带的文档。受影响的主要是自己拼装对话历史、做"伪造 assistant 回复"这类玩法的代码。

3. user 消息 text 块带非空 citations 数组：400

在 user 消息的 text 块（含 search_result 块内部）上带非空 citations 数组，同样 400。注意三条豁免：assistant 消息里的 text 块带 citations 仍然合法（比如把 Claude 之前的回复原样回传）；文档和搜索结果上的 "citations": {"enabled": true} 设置不受影响。这一条打中的主要是做 RAG 引用回传、自己管理引用标注的管线。

4. Admin API 与 Enterprise Analytics 字段改名

管理面的破坏性变更走的是"旧名彻底消失"路线，没有兼容期。RBAC 相关：roles→role_ids、group_id→rbac_group_id、name→display_name；限流相关：group_type→group.type；用量与成本报告：actor.email→actor.email_address，activity summaries 的 summaries→data。

最绕的是 API key 上的 workspace_id：旧版里它是 key 绑定的 workspace ID（Default Workspace 或全 workspace 的 key 返回 null）；新版里这个字段被移除，改读 scope——绑定 workspace 的 key 用 scope.workspace_id（这次是真实 ID，不再有 null 的歧义），全 workspace 的 key 的 scope 是 {"type": "organization"}。以前拿 workspace_id == null 来判断 Default Workspace 的代码必须重写，正确做法是调 List Workspaces（带 include_default=true）找到名为 "Default" 的 workspace 再比对 ID。

5. SDK 改用 Authorization: Bearer 鉴权头

新版 SDK 不再用 X-Api-Key 头发送 key，改用 Authorization: Bearer <key>。好消息是 Claude API 两边都接受，所以服务端没有硬切换；坏消息是所有读 X-Api-Key 的中间环节都要改：自建的 API 网关、代理转发、日志脱敏的中间件、测试桩，全部要 grep 一遍。自己拼请求头的人可以直接继续用 X-Api-Key，API 照收。

连带的一个设计变化：API key 和 auth token 现在共享同一个头，所以一个 SDK 客户端只持有一份凭据。两边都没传时走 credential precedence 顺序；如果你以前写过"删掉 X-Api-Key 让请求只带 token"的代码，现在要删掉这段逻辑——因为删 Authorization 会把 token 一起删掉。

ant CLI 2.0.0 则直接移除了 --api-key 和 --auth-token 两个 flag（从 1.27.0 起就一直在打 deprecation 警告），理由很实在：命令行参数会留在 shell 历史和进程列表里。替代方案是环境变量 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN、--api-key-stdin / --auth-token-stdin 从标准输入读，或者 ant auth login。

6. 与 API 版本无关的 SDK/CLI 破坏性变更

这一组变更不依赖你发哪个 API 版本，只要升级 SDK 大版本就会吃到，清单如下：

• Text Completions 被移除：从 TypeScript、Go、Java、Ruby 四个 SDK 和 CLI 里删掉。官方的理由是新模型和新特性都不再支持它，统一用 Messages API。
• TypeScript 与 Ruby SDK 移除客户端 compaction：tool runner 里的客户端压缩逻辑砍掉，改走服务端 compaction——对话摘要在 API 内部完成，不再需要客户端多发一次请求。注意触发阈值至少 50000 tokens，另有 pause_after_compaction 和自定义 instructions 等选项。
• MessageParam 按角色拆分：以前一个类型通吃所有角色，现在拆成 UserMessageParam、AssistantMessageParam、SystemMessageParam（beta 版同理）。SDK 实际发送的 JSON 字段和值不变，主要是 TypeScript 用户的类型体操要改。
• 单值枚举变常量：影响 C#、Go、Java、PHP、Ruby 五个 SDK 和一个 CLI flag。以前"只能取一个值"的必填字段各有一个单成员枚举类型，现在直接变成常量，枚举类型删除，收发的 JSON 不变。
• 非 beta Models 方法不再接受 betas：要发 beta 头改调 client.beta.models（CLI 里是 ant beta:models），返回值也从 ModelInfo 变成 BetaModelInfo；ant models 的 --beta flag 同步移除。

7. 许可证：MIT → Apache 2.0

从上述新版本起，所有 SDK 和 CLI（包括 TypeScript 的各平台包、C# 的 Bedrock/Vertex 等衍生包、Java 的全部 com.anthropic artifact）统一换成 Apache License 2.0，旧版本继续保持 MIT。官方明确说不需要任何代码变更，唯一要做的事是：如果你维护了依赖项的许可证清单，把这几条更新掉。对企业用户来说，Apache 2.0 明确的专利授权条款通常比 MIT 更容易过合规审查，这次更换大概率是利好。

谁会被 400 打中，谁可以睡个好觉

情况	结论
请求里带了 temperature / top_p / top_k（任何值）	会 400，必须删参数
靠调低 temperature 换输出稳定性的（Sonnet 4.6 等旧模型）	行为会变，无替代设置；可暂留 2023-06-01
只用 Claude 4.7 及更新模型，且一直用默认采样	行为不变，删掉参数即可
assistant 消息里直接拼 document 块	会 400，改放 user 消息
user 消息 text 块带 citations（RAG 引用回传常见）	非空即 400，删掉数组
读 Admin API / Analytics 字段名的内部工具	旧字段名消失，按改名表更新
自建网关/代理读 X-Api-Key 做鉴权或日志脱敏	改读 Authorization 头（API 两边都接受，可渐进）
脚本里用 ant --api-key 传 key	2.0.0 直接报错，改环境变量或 stdin
只调 Messages API 做简单问答，不碰采样参数	基本不受影响，升级 SDK 即可

迁移清单：照着做就行

官方推荐的升级顺序是三步：先切到 2026-10-21（SDK 升级大版本，或裸调时把 anthropic-version 头设为 2026-10-21），再逐条修破坏性变更，最后在新版本下完整测试一遍再发布。把上面的图展开成文字版：

• 删掉 temperature / top_p / top_k：全局搜索这三个参数名，全部删除。记住传默认值也会 400，不存在"传个 1.0 保平安"的选项。
• 把 assistant 消息里的 document 块移到 user 消息：检查拼装对话历史的代码。
• 删掉 user 消息 text 块上的 citations 数组：RAG 管线重点检查引用回传逻辑。
• 更新 Admin API 字段名：roles→role_ids、group_id→rbac_group_id、name→display_name、group_type→group.type、actor.email→actor.email_address、summaries→data；API key 改读 scope。
• 网关与中间件改读 Authorization 头：grep X-Api-Key，鉴权、日志脱敏、测试桩一个都别漏。
• 升级 SDK 大版本并处理移除的 API：Text Completions、客户端 compaction、MessageParam 类型拆分、单值枚举变常量、Models 方法的 betas 参数，逐个过。
• 把依赖清单里的 SDK 许可证更新为 Apache 2.0：无代码变更，纯台账工作。

同一天 release notes 里容易被忽略的另一件事

10 月 21 日的 release notes 条目其实有三段，前面只讲了第一段（API 版本和 SDK）。第二段值得做平台和网关的人留意：user profiles 新增了 enforcement_status 和 enforcement_actions 两个字段，可以查到 Anthropic 是否对你的某个终端客户做出了限制或封禁，配合新增的 enforcement_status[] 筛选条件，能直接列出"有未结限制或封禁"的 profile。

这个功能是为"转售 API 访问"的场景设计的：如果你运营的是平台、网关，或者把 Claude 能力打包卖给下游客户，以前一旦某个终端用户违规，Anthropic 的安全处置可能波及你整个组织；有了 user profiles，处置可以精确到单个终端客户。10 月 20 日的条目还配套推出了 organization webhooks（beta）：终端客户被限制/解封时，你的服务端能收到事件通知。虽然这是 Admin 面向的功能，不在这次 2026-10-21 迁移指南的破坏性变更清单里，但做 toB 网关的团队应该把它和鉴权头变更放在同一个升级窗口里一起处理——反正网关代码都要动一次。

为什么 Anthropic 一定要删掉采样参数？

删 temperature 这件事，表面看是"少了三个参数"，深层是 Anthropic 对 API 设计哲学的一次表态。三个证据拼在一起，方向非常清晰。

第一，新模型早就不再吃这一套。迁移指南里白纸黑字：Claude 4.7 及更新的模型本来就只接受默认值。也就是说，对最新模型而言，这三个参数过去几年里一直是"摆设"——传了非默认值会怎样？结合 10 月 7 日 Haiku 5.5 的迁移指南看，答案是直接 400。API 层面的删除，只是把模型层面已经发生的事实追认成全平台的规则。

第二，推理时代的采样控制正在失效。这两年大模型的能力增量主要来自推理（thinking / chain-of-thought），而 temperature 这类参数控制的是 token 采样的随机性——它诞生于"补全"时代。当模型的主要工作变成"先想再答"，用一个 0 到 1 的旋钮去调节输出质量，本身就越来越粗糙。Anthropic 的选择是：干脆收回这个旋钮，把"稳定、可控"的责任放到模型和 prompt 工程一侧。

第三，官方在逼开发者用"正确"的方式要确定性。过去 temperature=0 是事实上的标准答案，但它从来不是真正的确定性保证——同样的 prompt 在不同时间跑，结果依然可能漂移，还顺带把输出质量拉低（低温采样的通病）。Anthropic 等于在告诉你：要结构化就用 schema 约束，要稳定就写更明确的指令，要鲁棒就做校验和重试。这些工程手段比调一个参数贵，但它们是真的管用。

当然，质疑的声音也不会少：删参数等于把一部分控制权从开发者手里拿走，对那些确实需要高随机性做创意生成的场景（比如头脑风暴、文案发散），默认 temperature=1.0 是否够用，要实际跑过才知道。但至少有一点是确定的——在 2026-10-21 的世界里，"调参"这个动作本身已经不存在了，剩下的只有 prompt 和工程。

升级 SDK 大版本：各语言一句话注意事项

七个 SDK 同时跳大版本，迁移指南里"Switch to 2026-10-21"一节的原则是：用你当前语言列出的第一个新版本，它的默认 anthropic-version 就是 2026-10-21。各语言有一句话值得单独拎出来：

• Python（2.0.0）：如果你写过删 X-Api-Key 只留 token 的代码，现在删掉这段逻辑；检查 ANTHROPIC_API_KEY 与 ANTHROPIC_AUTH_TOKEN 同时设置时的凭据优先级是否符合预期。
• TypeScript（1.0.0）：改动最多——MessageParam 按角色拆成三个类型、客户端 compaction 移除改走服务端、Text Completions 删除、平台包（bedrock-sdk、vertex-sdk 等）各自发 1.0.0 并同步换 Apache 2.0 许可证。
• C#（13.0.0）：单值枚举变常量的影响面最大，凡是自己定义了对应枚举类型的封装代码都要改；衍生包（Anthropic.Bedrock、Anthropic.Vertex 等）各自发 1.0.0 换许可证。
• Go（2.0.0）：注意单值枚举变常量和 Text Completions 移除；Amazon Bedrock 与 Google Cloud 客户端同样默认发送新版本。
• Java（3.0.0）：许可证变更覆盖所有 com.anthropic artifact，企业用户更新依赖清单时别漏掉传递依赖。
• PHP（1.0.0）：从 0.x 直接到 1.0.0，语义化版本上这是"首个稳定版"，升级时建议把变更日志从 0.53.0 开始完整过一遍。
• Ruby（2.0.0）：和 TypeScript 一样吃了客户端 compaction 移除与 Text Completions 删除两条，tool runner 相关代码重点回归。

裸调 API（不用 SDK）的人最简单：把 anthropic-version 请求头设为 2026-10-21，然后按迁移清单逐条修请求体。官方建议把"切版本"和"修破坏性变更"放在同一次发布里一起上，避免中间态。

写给 vibe 开发者的四个判断

判断一：temperature 的删除，意味着"可复现性"玩法的终结

很多 vibe coding 项目里都有这么一行"祖传配置"：temperature=0，指望模型输出稳定、可复现。Anthropic 这次直接把桌子掀了：以后采样这件事不归你管。结合 Haiku 5.5 那边连 assistant prefill 都 400 的做法看，官方的态度非常明确——输出的稳定性应该由模型本身保证，而不是由调用方用采样参数去"调"。

对 vibe 开发者来说，替代路线只剩三条：把约束写进 prompt（"只输出 JSON，不要解释"这类硬约束比 temperature 好使）；用结构化输出和 schema 校验把不确定性挡在外面；对关键步骤做多次采样投票。以前靠 temperature 偷懒的那部分，现在要靠工程手段补回来。这不是坏事——temperature 本来也从来不是确定性的保证，只是心理安慰剂。

判断二：鉴权头统一，网关作者先 grep 再升级

这次变更里最容易在生产环境爆炸的其实不是 temperature，而是 X-Api-Key→Authorization。因为 API 两边都接受，服务端不会报错，炸的是你自己的网关逻辑：鉴权中间件读不到 key 直接放行或拒绝，日志脱敏规则失效导致 key 明文进日志。升级 SDK 之前，先在自己的网关、代理、中间件代码里 grep X-Api-Key，这一步的优先级应该排在删 temperature 之前。

判断三：Apache 2.0 是合规层面的加分项，但台账要更新

MIT 换 Apache 2.0，对绝大多数个人开发者和使用方没有任何实际影响，代码不用动。但如果你在公司项目里用，依赖审查（license audit）那一关：Apache 2.0 带明确的专利授权条款，过审通常比 MIT 更顺利。反过来，公司的合规清单里这几条 SDK 的许可证条目必须更新，否则下次审计会被挑出来。旧版本继续是 MIT，不存在追溯问题。

判断四：旧版暂不弃用是缓冲期，不是长期方案

官方这次没有给出 2023-06-01 的弃用时间表，依赖非默认值 temperature 的请求可以暂时不迁。但别把"双版本并存"当成长期架构：新 SDK 的类型定义里旧字段已经消失，你的代码早晚要改；而且 Anthropic 的新模型本来就只认新行为，旧版本只是给你争取了几个月的窗口。建议的策略是：新写的集成直接用 2026-10-21，老的按"删参数→改字段→切版本"的顺序排期迁，不要等到官方宣布弃用那天才动手——参考各家云厂商的惯例，弃用通知到真正下线通常只给 6 到 12 个月。

三年才等来一个正式版本，Anthropic 这次的手笔不算小：删采样参数是理念之争，改鉴权头是工程 hygiene，换许可证是合规成熟。这三件事放在同一个版本里，说明官方认为 Claude API 已经过了"快速试错"的阶段，开始为长期稳定做设计。对开发者来说，最好的回应就是按清单尽快迁过去——早迁早省心。毕竟，API 版本号三年才动一次，下一次再动，可能就不是"给缓冲期"这么温柔了。