Claude API 升到 2026-10-21,旧请求要改哪些地方
Claude API 2026-10-21 拒绝 temperature 等采样参数,并收紧消息块位置。升级 SDK 时还要检查默认 API 版本、MessageParam 用法和实际发出的请求。

Claude API 升到 2026-10-21 后,原来带着 temperature、top_p 或 top_k 的 Messages 请求会返回 400,写成默认值也一样。升级 SDK 还可能同时改变默认 API 版本,所以“我只更新了依赖,业务没改”并不能排除请求行为变化。
这次迁移需要一起检查请求构造、历史消息与 SDK 调用,不能只替换一个请求头。本文于 2026 年 11 月 22 日重读官方迁移指南与发布记录,聚焦 Messages 应用,不展开管理后台 API 的字段迁移。没有发送带认证请求,文中代码只做离线检查。
SDK 版本和 API 版本是什么关系?
SDK 主版本决定默认发送的 API 版本;模型 ID 决定这次调用哪个模型,两者不能混作同一个升级。
官方在 10 月 21 日发布新 API 版本,并列出首批默认使用它的 SDK:Python 2.0.0、TypeScript 1.0.0,以及其他语言的新主版本。直接调用 HTTP 的项目则显式设置 anthropic-version。
因此迁移记录至少保留三项:依赖锁定的 SDK 版本、实际发出的 anthropic-version、所用模型 ID。检查出站请求时隐藏认证值,不把 Key 放进截图或求助记录;保留必要元数据的方法见API 日志脱敏。
旧版请求并没有因为新版本发布就自动全部停止。依赖非默认采样行为的应用,应先看迁移指南允许的保留旧版本路径与当前模型支持情况,再计划切换。Amazon Bedrock 还有限制:新 API 版本仅适用于 Claude 4.7 及之后的模型,较早模型不能照抄升级步骤。
temperature 设成 1,为什么还是报错?
新 API 版本删除了 temperature、top_p、top_k 这三个请求参数,拒绝的是字段存在本身,不仅是某个不支持的值。
应从请求对象里移除字段,不要改成 null、0 或默认值后继续发送。检查的对象还包括:公共 SDK 包装器、客户端预设、工作流节点,以及 Message Batch 内的每条 Messages 请求。
下面是新版本请求体示例,没有采样字段。它还需要与 anthropic-version: 2026-10-21、合法认证和正确端点配合使用;本文未执行网络调用。
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Explain the difference between an API version and a model ID in two sentences."}
]
}
移除参数不等于保留了原来的低温行为。官方明确说明,原来允许非默认采样值的模型在新版本里失去这种调节效果,没有另一个设置能直接代替。需要固定格式时,可以评估结构化输出;它约束输出形状,也不保证每次内容完全一致。
同样,旧文中讨论Claude 文字水印与采样参数的条件不能直接用于新版本:先确认请求是否还允许发送这些参数,再看具体模型的平台覆盖。
保存的历史消息也要调整吗?
需要检查历史里内容块所在的角色,新版本会拒绝两类过去可能发送的内容。
| 内容形状 | 2026-10-21 行为 | 迁移方式 |
|---|---|---|
document 直接放在 assistant 消息里 | 返回 400 | 文档放在 user 消息里 |
user 消息的文本块带非空 citations,包括 search_result 内部 | 返回 400 | 去掉这些用户文本块上的引用数组 |
| assistant 先前回答中的文本引用 | 仍接受 | 保留模型返回的引用结构 |
文档或搜索结果的 citations: {"enabled": true} | 仍接受 | 这是引用开关,不是用户文本引用数组 |
不要为了修第二种问题,递归删除所有名为 citations 的字段。这样会把应该保存的 assistant 出处和开启引用的设置一起删掉。带出处的合同提取说明了为什么文本值与引用结构要一起保存。
官方还明确:模型返回的 web fetch 工具结果中,嵌套的文档仍可接受。直接位于 assistant 内容数组的文档与工具结果内部的文档不是同一形状。迁移脚本若只按字段名全局替换,很容易改坏本来合法的历史。
Python 代码和代理还要检查哪些变化?
Python 的 MessageParam 从单一 TypedDict 变成按角色区分的类型联合,旧的构造调用要改成字典。
from anthropic.types import MessageParam
message: MessageParam = {"role": "user", "content": "Hello"}
MessageParam(role="user", content="Hello") 在新 SDK 下会报 TypeError。如果消息角色来自变量,还要按角色分别构造,让类型检查器知道对应分支。本文只编译了新写法,没有安装 SDK 做运行时验证。
SDK 的其他改动还包括认证头:多数新 SDK 将 API Key 放到 Authorization: Bearer,而非原来的 X-Api-Key;具体平台客户端存在例外,按迁移指南检查。代理、日志脱敏器和测试桩若只识别旧头,需要单独核验。不要为解决一个 401,在日志里打印全部请求头或叠加两套真实凭据。
TypeScript 和 Ruby 工具运行器的客户端压缩也被移除,迁移指南指向服务端压缩。若应用用了这些功能,应另查对应语言章节;不能因为一轮纯文本聊天通过,就推断自动工具循环也已经完成迁移。
怎样证明这次升级没有破坏任务?
用独立测试环境验证当前应用真正依赖的路径,并把升级后的请求元数据和响应结构一起保存。
最小验收可以包含:一条纯文本问答、一份用户文档、一段含引用的旧历史、一次工具调用与结果续接;有流式或批处理的项目,再分别验证完整结束与逐条结果。先定义答案和行为的完成条件,不用“看起来还能聊天”作为唯一标准。
离线可以先检查 JSON 是否还含被删除字段,编译新调用写法,构造几种历史块确认迁移逻辑。这些检查不证明官方端点、代理鉴权或模型运行已经通过。 真实请求的失败应保留版本与具体错误,按调用链定位,不自动反复重试 400。
本站Claude 原生兼容文档目前的基本 HTTP 示例仍显式使用 2023-06-01。它不能证明新版本的全部约束、SDK 默认和 beta 功能已通过本站验收。经 Nbility 使用时,先按SDK 接入说明确认基础配置,再对实际 SDK、API 版本和完整任务逐项测试。


