temperature is deprecated for this model的原因与解决方法——Claude API的temperature与新API版本2026-10-21

如果 Claude API 返回以下错误，原因是你向 Claude 4.7 及之后的模型发送了 temperature（或 top_p、top_k）的非默认值。修复方法是从请求中删除这 3 个参数。在 2026 年 10 月发布的新 API 版本 2026-10-21 中，无论是哪个模型、无论取值多少，只要发送这些参数，就会返回 400 错误。

400 invalid_request_error
`temperature` is deprecated for this model.

向 Claude 4.7 及之后的模型发送非默认值时的响应示例（来自用户报告）。官方文档没有说明新 API 版本返回的错误信息是否相同。

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    temperature=0.2,
    messages=[...],
)

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[...],
)

本文以 Anthropic 官方文档（2026 年 10 月 26 日确认）为依据，说明出现此错误的两种情况、更新 SDK 时会发生什么、升级到新 API 版本时需要一并修改的内容，以及与之相近的错误 anthropic-version: header is required 的修复方法。API 版本用颜色区分：2023-06-01（之前的版本）和 2026-10-21（新版本）。

1. 出现错误的两种情况

Claude API 通过请求头 anthropic-version 选择 API 版本。是否会报错，取决于所用模型和 API 版本的组合。

出处：Anthropic《Migrating to API version 2026-10-21》（Claude 4.7 及之后的模型只接受默认值；Sonnet 4.6 等可接受其他值；2026-10-21 下，任何模型即使是默认值也返回 400），以及各模型的迁移指南（Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1；Fable 5.1 的指南写明其与 Opus 5 有相同的采样限制）。2026 年 10 月 26 日确认。

表中标为“400”的单元格对应以下两种情况。

1. 情况 1：对 Claude 4.7 及之后的模型，使用 2023-06-01 发送了非默认值（表格第一行、2023-06-01 列）
2. 情况 2：使用 2026-10-21 发送了这 3 个参数中的任意一个（无论模型和取值如何）（表格右侧一列）

开头的错误信息 `temperature` is deprecated for this model. 出现在情况 1 中，是一位用户在 GitHub 上报告的 API 响应（报告示例）。Anthropic 的官方文档没有收录该错误信息本身，只写明会返回 400 错误。

简而言之，两种情况都可以通过删除这 3 个参数来解决。如果你之前在较旧的模型上修改过取值，请注意删除后回答的波动程度会发生变化（见第 2 章）。

2. 修复方法，以及希望每次得到相同回答时

1. 从请求中删除这 3 个参数从 Messages API 的请求中删除 temperature、top_p、top_k，也要从 Message Batches 的每个请求中删除。如果配置文件或封装函数中设置了默认值，也请在那里删除。
2. 删除后的行为如果不发送这 3 个参数，就会使用默认值（temperature 默认为 1.0）来选择下一个 token。top_p、top_k 的默认值没有以数字形式给出，因此不发送是最稳妥的做法。这与之前的 API 版本中不发送这 3 个参数时的情况相同。Claude 4.7 及之后的模型本来就只接受默认值，因此行为不会改变。
3. 希望每次得到相同回答时没有可以替代的设置。Anthropic 的迁移指南建议通过提示词来引导模型的行为。该指南还写道，即使设置 temperature = 0，之前的模型也不保证回答相同。如果只是想统一回答的格式，可以使用结构化输出（Structured outputs），定义 JSON 的结构并让模型按此返回。

例外的情况是：使用 Claude Sonnet 4.6 这类接受其他值的模型，并且之前通过调低取值来减少回答的波动。在新 API 版本下只能删除，这一效果也随之消失。Anthropic 的建议是：要么让该请求继续使用 2023-06-01，要么停止发送这些参数。要继续使用 2023-06-01，可以让 SDK 保持在当前的主版本（Python 为 1.x），如果是直接调用 HTTP，则保持请求头为 anthropic-version: 2023-06-01。迁移指南中没有说明如何在新 SDK 中逐个请求选择较旧的 API 版本。

TypeScript 与 HTTP 中的修复方法

// TypeScript（@anthropic-ai/sdk）：删除 temperature
const msg = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});

# HTTP（JSON 请求体）：不要写入 temperature、top_p、top_k 这几行
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello, Claude"}]
}

3. 查找自己的代码在哪里发送了这些参数

如果不知道错误来自哪里，可以用这 3 个参数的名称在代码中搜索。即使不是你自己写的代码，也常会在配置文件、公共函数或环境变量中设置默认值。

# macOS、Linux、WSL：在项目中搜索（不区分大小写）
grep -rniE "temperature|top_p|top_k" --exclude-dir={node_modules,.venv,venv,.git,dist} \
  --include="*.py" --include="*.ts" --include="*.js" --include="*.json" \
  --include="*.yaml" --include="*.yml" --include="*.toml" --include=".env*" .

# Windows（PowerShell）
Get-ChildItem -Recurse -Include *.py,*.ts,*.js,*.json,*.yaml,*.yml,*.toml,.env* |
  Where-Object { $_.FullName -notmatch "node_modules|\\.?venv|\\.git\\|\\dist\\" } |
  Select-String -Pattern "temperature|top_p|top_k"

新 API 版本的规则适用于 Messages API 请求、计算 token 数的请求，以及 Message Batches 的每个请求（Anthropic 迁移指南）。

4. 更新 SDK 时会发生什么

官方 SDK 会自动发送其主版本发布时对应的 API 版本。从下表所列的 SDK 版本起，会发送 2026-10-21，并且删除的 3 个参数也已从 SDK 的类型中移除（Anthropic 迁移指南）。因此，更新 SDK 后，问题可能先以类型检查错误或“函数中没有该参数”的错误形式出现，而不是 API 的 400 错误。如果没有通过类型定义，而是把参数追加到请求体中（例如使用可追加请求体内容的功能，或直接通过 HTTP 发送请求），则 API 会返回 400。两种情况的修复方法相同：删除这 3 个参数。

出处：Anthropic《Migrating to API version 2026-10-21》中的 Upgrade steps。若不使用 SDK 直接调用，将请求头 anthropic-version 设为 2026-10-21 即可使用新 API 版本。

新 API 版本可用于 Claude API、Claude Platform on AWS、Google Cloud 上的 Claude（包括 Anthropic 管理和 Google 管理两种方式）以及 Microsoft Foundry。仅在 Amazon Bedrock 上，可用的只有 Claude 4.7 及之后的模型。如果你在那里调用较旧的模型，Anthropic 建议保持当前的 SDK 版本（或当前的 anthropic-version）（Versions）。

更新 SDK 的步骤

1. 切换到新 API 版本将 SDK 升级到上表中的版本。若直接调用 HTTP，则设置 anthropic-version: 2026-10-21。
2. 修复破坏性变更删除这 3 个参数，并修复第 5 章表格中适用于你的内容。新 SDK 中变化的写法（如类型名称）也请在迁移指南的“SDK and CLI changes”中确认。
3. 在新 API 版本下测试后再发布上线前，先在新 API 版本下测试请求能否正常通过。SDK 升级与修复应在同一次发布中完成。

出处：Anthropic《Migrating to API version 2026-10-21》中的 Upgrade steps（Switch to 2026-10-21 → Update your code for the breaking changes → Test against 2026-10-21）。

5. 使用新 API 版本时一并修复的内容

升级到新 API 版本时，除了 temperature，还有以下变更（API 密钥那一行仅涉及 SDK 和 CLI 的变更，如果直接通过 HTTP 调用则无关）。只修改适用于你的项目的部分（同一迁移指南中的 Breaking changes）。

6. anthropic-version: header is required 的修复方法

当请求中缺少 API 版本请求头时，会出现以下错误。

400 invalid_request_error
anthropic-version: header is required

官方 SDK 会自动发送 API 版本，因此这种错误主要出现在不使用 SDK、直接通过 HTTP 调用的情况下。例如，GitHub 上有报告称：将为 OpenAI 设计的客户端或工具指向 Claude 的 API 地址，并尝试读取模型列表（/v1/models）时会出现此错误（示例 1、示例 2）。

修复方法是添加该请求头。新写的代码请指定 2026-10-21；如果想在不改动现有代码的情况下正常运行，则指定 2023-06-01。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{"model": "claude-opus-5-5", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "Hello, Claude"}]}'

出处：Anthropic《Versions》（请求中必须包含 anthropic-version 请求头；SDK 会自动发送）。错误信息来自用户在 GitHub 上报告的 API 响应。API 密钥可通过 x-api-key 或 Authorization: Bearer 请求头中的任一方式传递（迁移指南）。

如果你使用的工具无法添加请求头，请确认该工具是否支持 Claude API（是否误以 OpenAI 的格式在调用）。

总结

FAQ

Q. 把 temperature 设为 1.0（默认值）再发送，也不行吗？

在新 API 版本 2026-10-21 中，即使是默认值，发送也会返回 400。如果你用 2023-06-01 调用 Claude 4.7 及之后的模型，默认值可以正常运行，但发送它没有意义，所以删除是最稳妥的做法。

Q. 我之前把 temperature 设为 0，以便每次得到相同的回答。替代方案是什么？

没有替代设置。Anthropic 迁移指南写道，即使是 temperature = 0，也从未保证回答相同。如果想统一回答的格式（如 JSON 字段），可以使用结构化输出，并在提示词中详细说明措辞和判断标准。

Q. 不升级到新 API 版本，继续使用当前版本可以吗？

可以。Anthropic 表示，每个 API 版本都会保留既有的输入和输出字段，2023-06-01 也仍可照常指定。Versions 页面没有说明 2023-06-01 何时停止提供（Versions，2026 年 10 月 26 日确认）。不过，对于 Claude 4.7 及之后的模型，即使使用 2023-06-01，非默认的 temperature 等参数仍会返回 400。另外，Anthropic 建议尽可能使用较新的 API 版本，升级 SDK 后会自动切换到新版本。

Q. 换成 Claude 4.7 及之后的模型后出现了错误

换成 Claude 4.7 及之后的模型后，即使 API 版本不变，非默认的 temperature 等参数仍会返回 400。关于换模型时需要修改的其他地方（如思考设置、预填充等），请参阅“Claude Opus 4.7 迁移指南”。