先给结论: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 组 | roles | role_ids |
| 组成员 | group_id | rbac_group_id |
| RBAC 角色 | name | display_name |
| 速率限制 | group_type | group.type |
| API 密钥 | workspace_id | scope.workspace_id 或组织级 scope.type |
| 分析:用户报表 | actor.email | actor.email_address |
| 活动摘要 | summaries | data |
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
}
常见问题 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 主版本升级和请求体清理应同一次发布。