ClaudeAPI MigrationSDKMessages API

Claude API 升到 2026-10-21,旧请求要改哪些地方

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

查看接入文档
Claude API 升到 2026-10-21,旧请求要改哪些地方

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 及之后的模型,较早模型不能照抄升级步骤。

依赖版本决定 SDK 默认,API 请求头选择协议行为,模型 ID 再决定模型能力

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 版本和完整任务逐项测试。

相关文章

用 Nbility 跑通你的 Agent 工作流

获取 API Key,统一接入 OpenAI 兼容模型和开发工具。

获取 API Key