Claude API 出了新版本 2026-10-21，SDK 和 ant 同时升大版本：temperature 不能再传，key 改用 Bearer 发送

2026 年 10 月 21 日，Claude API 发布了新版本 2026-10-21。官方的说法是，这是 2023 年以来第一个正式的版本更新，以后会更常发新版本，好让大家在新模型要求之前先处理掉不兼容的改动。旧版本 2023-06-01 没有弃用，照常能用。

同一天，各语言的 SDK 和命令行工具 ant 都出了大版本，默认就发 2026-10-21：Python 2.0.0（当天又出了 2.1.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。

和本站读者关系最大的是三点：

• 请求里不能再带 temperature、top_p、top_k。 新版本下带了就是 400，哪怕是默认值，哪个模型都一样。
• 新版 SDK 和 ant 改用 Authorization: Bearer 发 key。 以前放在 X-Api-Key 头里。官方接口两种都认；只认 X-Api-Key 的代理或网关要改。
• 经中转站时，新版本的规则不一定生效。 本站补测，同样的请求直连官方返回 400，经酷站AI 返回 200，见下文。

新版本改了什么

按官方的迁移指南，接口这边是三类改动：

改动	新版本下的结果	要怎么改
请求带 temperature、top_p、top_k	400，任何值都不行	删掉这三个参数。不带时按默认值采样（temperature 是 1.0），和旧版本不带它们一样
assistant 消息里直接放 document 块	400	文档放进 user 消息。嵌在别的块里的（比如 Claude 返回的网页抓取结果）照样能用
user 消息里的 text 块带非空的 citations，包括 search_result 块里的	400	去掉这些 citations。assistant 消息里的引用、文档和搜索结果上的 "citations": {"enabled": true} 照样能用

这三条对 Messages API、token 计数，以及用新版本建的批处理里的每个请求都适用。

关于采样参数，迁移指南特地说了一句：Claude 4.7 及以后的模型本来就只接受默认值，去掉以后采样不变；像 Sonnet 4.6 这样还接受别的值的模型，以前靠调低 temperature 求稳定的，新版本下没有别的设置能替代。

管理类接口这边是字段改名，新版本的响应里不再有旧名字：

• Admin API。 RBAC 组的 roles 改成 role_ids；组成员的 group_id 改成 rbac_group_id；角色的 name 改成 display_name；限流条目的 group_type 改成 group.type。
• API key。 不再返回 workspace_id，改看 scope：绑在某个工作区（包括默认工作区）的 key，scope.workspace_id 是那个工作区真正的 ID；能用所有工作区的 key，scope 是 {"type": "organization"}。以前把 workspace_id 为 null 当成默认工作区的代码要改。
• Enterprise Analytics API。 按人的用量和花费报表里，actor.email 改成 actor.email_address；活动汇总的 summaries 改成 data。

SDK 和 ant 要改的地方

这些是新大版本自己的改动，和接口版本无关，升级 SDK 就会碰到：

• key 改用 Authorization: Bearer 发送。 Python 的 api_key 和 ANTHROPIC_API_KEY、TypeScript 的 apiKey、ant 的 ANTHROPIC_API_KEY 和 --api-key-stdin 都是这样。官方接口两种头都认，所以直连的程序不受影响；中间有代理或网关读 X-Api-Key 的，要改成读 Authorization，或者按迁移指南在 SDK 的 HTTP 客户端上把 key 挪回 X-Api-Key。ant 没有加自定义头的办法，只能改网关。
• 一个客户端只能拿一种凭据。 同时传 api_key 和 auth_token 会报错。
• MessageParam 拆成按角色分开的几种类型，直接调用它会报错。
• ant 去掉了 --api-key、--auth-token 两个参数，改用环境变量或 --api-key-stdin；ant completions create 也删了。TypeScript、Go、Java、Ruby 的 SDK 里，旧的 Text Completions 接口删了。
• TypeScript 和 Ruby 的 tool runner 去掉了客户端压缩，改用服务端压缩。
• 非 beta 的 Models 方法不再接受 betas。
• 许可证从 MIT 改成 Apache 2.0。

本站补测：直连官方和经中转站不一样

10 月 22 日在服务器上用 Python SDK 1.13.0（旧大版本，没有升级），手动带上 anthropic-version 头，一条直连官方接口（官方 key），一条经酷站AI 中转站。旧版 SDK 已经没有 temperature 参数，所以用 extra_body 传。

请求	直连官方	经酷站AI
2026-10-21，不带采样参数	200	200
2026-10-21，temperature: 0.2、1.0 或 top_p: 0.9	400，temperature: Extra inputs are not permitted（top_p 那条同样）	200
2026-10-21，assistant 消息里放 document 块	400，`document` blocks can't be placed directly in `assistant` messages	200
2023-06-01，Opus 5.5、Sonnet 5.5、Haiku 5.5 带 temperature: 0.2	400，`temperature` is deprecated for this model.	200
2023-06-01，三个模型带 temperature: 1.0（默认值）	200	200
直连时用 Authorization: Bearer 代替 x-api-key	两个版本都 200	—

直连官方的结果和文档一致。经酷站AI 的全部是 200，说明新版本的规则没有在这家中转站上生效：可能是它没有把版本头带到上游，也可能是它自己去掉了这些字段，本站从外面分不出来。酷站AI 认 Bearer 头，本站经它调接口一直用的就是 Bearer。

同一天又装了新大版本实际跑了一遍。 Python 2.1.0、TypeScript 1.1.0 和 ant 2.1.0 装在服务器上的单独目录里：

• 在本机假网关上用假 key 看，三样都只发 Authorization: Bearer，默认发 2026-10-21。
• 两个环境变量都设时只用 ANTHROPIC_API_KEY，在 stderr 提示一次；代码里同时传两种凭据直接报错（Python 是 ValueError，TypeScript 是 TypeError）。
• Python 2.1.0 的 messages.create() 没有 temperature 参数，传了报 TypeError。ant 的 --api-key 参数和 completions create 都没了。
• 迁移指南给的把 key 挪回 X-Api-Key 的写法（Python、TypeScript），假网关上只收到 X-Api-Key；Python 的这段经酷站AI 也通了。
• 真实请求经酷站AI 和直连官方都通了，差别和上表一样：assistant 里放 document、带 temperature，直连官方 400，经酷站AI 200。
• OpenTelemetry 的 span 在 2.1.0 下和 1.14.0 完全一样。

这对经中转站的读者意味着两件事：

• 在中转站上测通，不代表直连官方也通。 迁移到新版本时，要用官方的 key 或者能如实转发的网关再测一遍。
• 别家中转站不一定认 Bearer。 升级 SDK 之前，先用 auth_token（Python）或 authToken（TypeScript）这种本来就发 Bearer 的写法试一下，看中转站认不认。

另外，表里第四行也更正了本站《升级到 Claude 5.5 一代》里的一处：那篇当时是经中转站测的，看到 temperature: 0.2 在 5.5 模型上返回 200，以为和文档不一致；直连官方实际是 400，和文档一致。那篇已经按这次的补测改了。

要不要升级

不急。2023-06-01 没有弃用。想升级的，迁移指南给的顺序是：先把 SDK 或 ant 升到新大版本（直接调接口的，把 anthropic-version 头改成 2026-10-21），再按上面几类改动改代码，最后在新版本上测过再上线。用 Claude Code 的，2.1.307 起可以让 /claude-api api-version 帮你改，见2.1.306 到 2.1.307 的快讯。

本站 Claude API 系列的实测是在旧大版本（Python SDK 1.13.0、TypeScript SDK 0.133.0、ant 1.40.0）和 2023-06-01 上做的，各篇里涉及这几处的地方已经注明；《Claude 的 SDK 和命令行》《在自己的代码里接中转站》两篇的主要用法，10 月 22 日用新大版本补测过。SDK 和命令行怎么装、怎么配，见《Claude 的 SDK 和命令行》。