升级到 Anthropic API 版本 2026-10-21 之后,为什么请求里还带着 temperature 就会直接 400?

截至 2026 年 10 月 26 日:2026-10-21 拒绝 Messages 中的 temperature、top_p、top_k(含默认值)。Python SDK 2.0 默认发送该版本。另需处理 document、citations 与 Admin 响应字段改名。

先给结论:2026-10-21 会把 Messages 请求里出现的 temperature、top_p、top_k 一律当成非法字段,哪怕你传的是文档里的默认值也会 400。Python SDK 2.0、TypeScript SDK 1.0 和 ant CLI 2.0 默认就带 anthropic-version: 2026-10-21。升级主版本后,旧请求体里若还留着这三个键,失败点往往在 JSON 校验之前。同一天发布的用户档案接口还多了 enforcement_status 与 enforcement_actions,Admin API 若干响应字段也改名,解析脚本要一起改。

这篇按 2026 年 10 月 26 日写,依据 10 月 21 日的迁移指南与版本说明。前天本站写过《OpenAI Decisions API 的 answers JSON》。那边是固定答案形状;这边是 Messages 请求体与 Admin 响应体的破坏性字段变更。

什么时候会悄悄切到 2026-10-21

迁移指南写明:SDK 主版本发布时绑定的 API 版本会随请求自动发送。升到 Python anthropic 2.0.0、TypeScript @anthropic-ai/sdk 1.0.0、Go anthropic-sdk-go/v2 2.0.0 等,就不必再手写版本头也会走 2026-10-21。裸 HTTP 调用则要显式设 anthropic-version: 2026-10-21。

Amazon Bedrock 上,2026-10-21 仅适用于 Claude 4.7 及以后模型;Opus 4.6 及更早型号若强行升 SDK 却未换模型,仍应留在旧 SDK 或旧版本头。Google Cloud、Foundry 与直连 Claude API 的适用范围以官方版本页为准。

三个采样字段为什么必须删掉

在 2023-06-01 上,省略 temperature 等价于默认 1.0。在 2026-10-21 上,出现键名即错误,不是值不对才报错。配置中心、特性开关或 ORM 若默认注入 "temperature": 0,升级当天就会全量 400。

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Summarize this ticket."}]
}

Claude 4.7 及以后本来就只接受默认采样,删掉字段后行为与以前「不传」一致。若你还在 Claude Sonnet 4.6 等老型号上靠 temperature: 0.2 压随机性,迁移指南写明没有替代参数:要么接受默认 1.0,要么该条请求继续用 2023-06-01。Message Batch 里每条子请求同样适用。

Messages 里另外两处 400

除采样字段外,2026-10-21 还收紧了两类 content block:

  • assistant 消息里的 document:不能把 document 块直接放在 role: assistant 下;应放在 user 消息,或保留嵌在 tool 结果里的 document。
  • user 消息里带 citations 的 text:user 角色下 text 块的 citations 数组不能为空;assistant 侧回传的引用文本仍允许。文档级 "citations": {"enabled": true} 不受影响。

多轮 Agent 把搜索结果塞回上下文时,最容易踩第二条:把带 citations 的 user 块原样 replay,会在新版本下 400。

Admin 响应 JSON 字段改名

若你的运维脚本解析 Admin API 或 Enterprise Analytics 响应,2026-10-21 起旧字段名不再出现,需要改 JSONPath 或类型定义:

场景旧字段新字段
RBAC 组rolesrole_ids
组成员group_idrbac_group_id
RBAC 角色namedisplay_name
速率限制group_typegroup.type
API 密钥workspace_idscope.workspace_id 或组织级 scope.type
分析:用户报表actor.emailactor.email_address
活动摘要summariesdata

API 密钥尤其容易误判:以前 workspace_id: null 可能表示 Default Workspace;现在应读 scope,全组织密钥是 {"type": "organization"},绑定工作区时 scope.workspace_id 为真实 ID。列表过滤参数 workspace_id 查询串未改,变的是响应体形状。

user profiles 与 enforcement 字段

10 月 21 日发行说明还加了用户档案上的 enforcement_status 与 enforcement_actions,用于判断终端用户是否被限制或封禁。列表接口可用 enforcement_status[] 过滤。这与版本头无直接关系,但常与 SDK 2.0 同一周上线;合规流水线应把这两项和 Messages 升级一起测。

升级时要留的请求快照

灰度时至少记录:

{
  "anthropic_version": "2026-10-21",
  "sdk": "anthropic-python-2.0.0",
  "model": "claude-sonnet-5-5",
  "request_keys": ["model", "max_tokens", "messages", "system"],
  "has_temperature": false,
  "has_top_p": false,
  "has_top_k": false,
  "http_status": 200
}
  • JSON 校验 — 确认出站 Messages 体里没有那三个采样键。
  • JSON Diff — 对比升级前后 Admin 列表响应的字段名。
  • JSONPath — 例如从密钥列表取 $.data[*].scope.workspace_id。

常见问题 FAQ

只升级 SDK、请求 JSON 没改,也会 400 吗?

会,只要请求体仍含 temperature、top_p 或 top_k 任一键。新版本 API 不认这些字段,与 SDK 是否已删类型无关。要从序列化层或中间件去掉键名。

传 temperature 1.0 算不算默认值可以保留?

不算。迁移指南写明即使等于默认值也返回 400。必须整键删除,不能改成 1.0 继续传。

Message Batch 的子请求也要删吗?

要。用 2026-10-21 创建的批次里,每条子请求遵守同一套 Messages 规则,包括采样字段与 document、citations 限制。

Bedrock 上的 Opus 4.6 能直接升 SDK 2.0 吗?

迁移指南建议 Opus 4.6 及更早 Bedrock 型号继续用旧 SDK 或旧版本头,或先换 Claude 4.7+ 再切 2026-10-21。否则版本与模型能力不匹配。

Admin 列表还能用 workspace_id 过滤吗?

查询参数 workspace_id 未改。变的是响应里 API 密钥对象不再顶层返回 workspace_id,应解析 scope。

enforcement_status 必须设 2026-10-21 才有吗?

用户档案字段随 10 月 21 日平台更新发布,与 Messages 破坏性变更同一波文档。集成时应确认你用的 Admin 或 Profile 端点版本与字段说明一致。

总结

2026-10-21 的核心是「字段不存在」而不是「值非法」。删掉 temperature、top_p、top_k;检查 assistant document 与 user citations;Admin 与 Analytics 响应改读新键名。SDK 主版本升级和请求体清理应同一次发布。