Anthropic API 2026-10-21：temperature 设为 1.0 也返回 400

使用 API 版本 2026-10-21 发送 Claude 请求时，只要设置了 temperature、top_p 或 top_k，就会返回 HTTP 400，即使传的是默认值也一样：temperature: 1.0 会报错“temperature: Extra inputs are not permitted”。这些采样参数控制模型选择下一个 token 时的随机程度。API 版本由请求头 anthropic-version 指定，决定 Messages API 如何校验和响应请求；旧版本为 2023-06-01。Anthropic 在 10 月 21 日同步发布的 SDK 大版本（Python 2.0.0、TypeScript 1.0.0 及另外五个 SDK）默认发送新版本号。这些 SDK 已彻底移除采样参数，因此，触发 400 的是自行构造请求体的代码，包括直接发送 HTTP 请求的客户端，以及通过额外请求体字段传参的代码。我们在 Claude Sonnet 4.6 和 Claude Sonnet 5.5 上，分别用两个 API 版本测试了八种请求结构，对比了两个 Python SDK 版本，并通过 Synthorai 重复了测试。

TL;DR

• 在 2026-10-21 下，Claude Sonnet 4.6 和 Sonnet 5.5 收到 temperature、top_p 或 top_k 都会返回 400，temperature: 1.0 也不例外。
• 2026-10-21 还会拒绝 assistant 消息中的 document 块，以及 user 文本块上的 citations。
• Anthropic Python SDK 2.x 通过 Authorization: Bearer 发送密钥；如果请求同时带有两种认证头，API 使用 x-api-key。
• 通过 Synthorai 测试时，无论使用哪个 SDK，全部 32 个请求都返回 200，包括 Anthropic API 在 2026-10-21 下拒绝的 12 个请求。

API 版本 2026-10-21 下，哪些请求会返回 400？

导致 400 的变更有五项：三个采样参数、直接放在 assistant 消息中的 document 块，以及 user 消息文本块上的 citations（从文本块指向文档中某段内容的引用）。下表将这些变更拆成六个失败用例，另加两个仍能通过的用例。我们针对每个模型和版本，分别向 Anthropic API 直接发送了每个用例一次。200 表示请求被接受；400 表示请求被拒绝，错误类型为 invalid_request_error。

新版本返回的错误信息：

Claude Sonnet 5.5 在 2023-06-01 下就已经拒绝非默认的采样参数值，但错误信息不同（“`temperature` is deprecated for this model.”），而且仍接受 temperature: 1.0。在 2026-10-21 下，参数本身已被移除，所以默认值也会失败。Claude Sonnet 4.6 在旧版本下则接受所有测试用例。Anthropic 的迁移指南指出，同样的规则也适用于 token 计数，以及 Message Batch 中的每个请求（Batch API 以折扣价格异步执行大量请求），但没有给出 2023-06-01 的停用日期。

各类 400 错误怎么修？

删除三个采样参数，将文档移到 user 消息中，并移除以 user 身份发送的文本中的 citations。不传采样参数时，请求会按默认值采样，包括 temperature 为 1.0；这与 2023-06-01 请求不传这些参数时的行为一致。Claude 先前回复中的引用，以及文档上的 "citations": {"enabled": true}，仍然可以使用。

使用 Python SDK 时，下面的请求在两个 API 版本下都能运行：

import anthropic

client = anthropic.Anthropic()  # 2.x sends anthropic-version: 2026-10-21

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    # no temperature, top_p or top_k: the parameters no longer exist in 2.x
    messages=[{"role": "user", "content": "Summarize this memo in one sentence."}],
)
print(message.content[0].text)

如果某个请求需要非默认的 temperature，且模型仍支持该值，例如 Claude Sonnet 4.6，这个请求就必须继续使用旧版本。直接发送 HTTP 请求时，需要自行设置请求头：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 256, "temperature": 0.2,
       "messages": [{"role": "user", "content": "Pick a number from 1 to 100."}]}'

Anthropic SDK 有哪些变化？

默认发送 2026-10-21 的 SDK 大版本包括 Python 2.0.0、TypeScript 1.0.0、Go 2.0.0、Java 3.0.0、C# 13.0.0、PHP 1.0.0 和 Ruby 2.0.0。除了 API 版本，它们还更改了密钥的发送方式、单个客户端可持有的凭据数量，并将许可证从 MIT 改为 Apache 2.0。我们安装了 Python SDK 1.17.0（最后一个 1.x 版本）和 2.3.0，分别连接本地回显服务器，记录收到的每个请求的请求头和请求体：

Python SDK 在 1.0.0 中就已从消息方法中移除了 temperature 参数，因此 Python 用户只有通过 extra_body（向请求体添加原始字段的 SDK 选项），或通过自行构造请求体的 HTTP 客户端和库，才会遇到服务端的 400。Bearer 请求头在两个 API 版本下都可用：仅携带 Authorization: Bearer <key> 的请求在 2023-06-01 下也返回了 200，因此认证方式和 API 版本可以分开迁移。

同时发送两种请求头时，实际使用哪个密钥？

如果请求同时携带两种请求头，Anthropic API 使用 x-api-key。我们在两个 API 版本下测试了五种请求头组合：

Claude 前面的代理或网关，可能对请求使用了哪个密钥作出与 API 不同的判断。使用 SDK 2.x 时，通过 extra_headers={"X-Api-Key": other_key} 添加第二个密钥的代码，现在会发送两个密钥：Authorization 中是客户端的密钥，x-api-key 中是另一个密钥。Anthropic API 使用 other_key 认证，而只读取 Authorization 的代理会认为请求使用的是客户端密钥。这样，按密钥统计的配额、日志和支出限额就可能归到错误的密钥上。迁移指南给出的客户端修复方式，是通过 Authorization: Bearer <other_key> 发送第二个密钥。代理端则应读取两个请求头，按 API 的优先级处理（x-api-key 优先），或者直接拒绝两个请求头携带不同密钥的请求。

移除 temperature 会失去什么？

对于依赖 temperature: 0 的团队，移除 temperature 的影响可能比预期小。迁移指南指出，Claude 4.7 及后续模型本就只接受默认值，因此对这些模型没有影响。对于仍支持其他值的模型，例如 Claude Sonnet 4.6，原先通过降低 temperature 来稳定输出的请求，会失去这一效果，也没有其他设置可以替代。我们测量了这个效果有多大：在 2023-06-01 下，对 Sonnet 4.6 的每种设置各发送 20 个请求，每次都在提示词后附加随机请求 ID，确保没有两个请求完全相同。

在这些短回答中，Sonnet 4.6 使用默认 temperature 时，输出的集中程度与设为 0 时基本相当，因此移除 temperature: 0 几乎没有影响。temperature: 0 本来也不保证确定性：20 次请求仍返回了两个不同的数字。提示词文本对输出的影响比参数更大：不附加请求 ID 时，最常见的答案是 42（temperature: 0 下 20 次中出现 17 次）；附加后，最常见的则是 47。如果需要可重复的输出，应在代码中比较答案或缓存结果；采样参数此前也无法保证这一点。

Synthorai 如何处理 API 版本 2026-10-21？

Synthorai 接受两个 API 版本及两个 SDK 发来的请求，因此升级到 SDK 2.x 或发送 anthropic-version: 2026-10-21，不会让原本可用的请求失败。我们通过 Synthorai，分别使用两个 anthropic-version 值，重复了覆盖两个模型的 16 个测试用例：全部 32 个请求均返回 200，包括 Anthropic API 在 2026-10-21 下拒绝的 12 个请求。Python SDK 1.17.0（发送 x-api-key）和 2.3.0（发送 Authorization: Bearer）使用 base_url="https://synthorai.io" 和同一个密钥都能正常工作，通过 extra_body 发送 temperature 也一样。

Synthorai 这样处理有四个原因：

• 同一个模型有多个托管平台。Claude 模型可以由 Anthropic API、Amazon Bedrock 或 Google Cloud Vertex AI 提供，每个平台使用各自的版本字符串。Synthorai 会向各个平台发送其要求的版本，因此客户端的 anthropic-version 请求头不决定请求如何校验。
• 迁移期间新旧客户端并存。团队通常逐个服务升级，因此连续几周内，同一个账户可能既有 SDK 1.x 发送的 2023-06-01，也有 SDK 2.x 发送的 2026-10-21。同时接受两者，各个服务就能按自己的节奏迁移，同一个密钥也能配合两个 SDK 的认证头使用。
• 切换模型时不必改代码。为 Claude Sonnet 4.6 设置了 temperature: 0.2 的代码，在模型名改为不支持该参数的 Claude Sonnet 5.5 后仍可运行，不会因切换模型而报错。
• 不因默认值而拒绝请求。temperature: 1.0 本来就是模型使用的值，拒绝它只会让请求失败，并不会改变输出。

代价是，返回 200 不代表每个参数都生效。Sonnet 5.5 只接受默认采样值，因此通过 Synthorai 向它发送 temperature: 0.2 虽然能成功，却无法降低输出的随机性。如果输出依赖某个采样值，应使用自己的提示词，对比传入和不传入该值时的结果；上面的测试发现，它对短回答的影响很小。

升级前应该检查什么？

常见问题

为什么 Claude 请求会报“temperature: Extra inputs are not permitted”？ 请求使用了 anthropic-version: 2026-10-21，这个版本已移除 temperature 参数，因此传入任何值都会返回 400，包括 1.0。新版 SDK 大版本默认发送该版本号。删除此参数即可；如果模型仍支持非默认值，且请求确实需要使用，就为该请求固定使用 2023-06-01。

anthropic-version 2023-06-01 要停用了吗？ Anthropic 尚未公布 2023-06-01 的停用日期：迁移指南和 10 月 21 日的 API 发布说明都没有给出日期。显式设置该请求头的请求仍保持旧行为，因此可以让单个请求继续在 Claude Sonnet 4.6 上使用 temperature。

Anthropic API 还接受 x-api-key 请求头吗？ Anthropic API 的两个版本都接受 x-api-key 和 Authorization: Bearer；只是 SDK 更改了默认发送的请求头。两个请求头同时存在时，API 使用 x-api-key。

相关阅读

• Claude Sonnet 5.5 费用：与 Sonnet 5 相比，这个模型的费用如何
• LLM 思考控制参数：较新的 Claude 模型仍然支持哪些推理设置
• OpenCode 泄露事件：保护 API 密钥：限制密钥泄露后的影响
• LLM API 速率限制：按密钥设置的限额如何计数

← 返回博客