Claude API 模型 ID 怎么写、怎么查可用模型：dateless 命名、别名区别、Models API 的 lifecycle 和 capabilities

本文根据 Claude 开发者平台官方文档《Models overview》《Model IDs and versioning》《List Models》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 写 Claude API 代码，不知道 model 该填什么字符串的人；
• 看到别人写 claude-sonnet-4-5-20250929，自己写 claude-sonnet-5-5，想弄清带不带日期有什么区别的人；
• 想在程序里自动列出当前可用模型、判断某个模型是否支持某项功能的人。

模型之间怎么选，见 /guides/claude-models-compare 和 /guides/claude-opus-vs-sonnet；基础调用见 /guides/claude-api-python-quickstart。

结论先说

1. 每个模型 ID 都是一个固定的版本快照。 官方说，用某个模型 ID 发请求，该 ID 对应的底层模型在整个生命周期内保持不变；更新的版本会以新的 ID 发布。
2. 4.6 代及之后用不带日期的格式： claude-{name}-{major}[-{minor}]，例如 claude-opus-4-8、claude-sonnet-5。大版本发布（如 Sonnet 5、Opus 5）省略 minor。
3. 4.6 之前的模型带快照日期： claude-{name}-{major}-{minor}-{YYYYMMDD}，例如 claude-sonnet-4-5-20250929；Claude API 上它们还有不带日期的别名（如 claude-sonnet-4-5），指向该小版本最新的带日期快照。
4. 不带日期不等于「永远最新」。 官方专门澄清：claude-sonnet-4-6 这类 ID 不是别名，它就是那个快照，不会被悄悄换成更新的版本。
5. 用 Models API 查： GET /v1/models 返回你能用的模型，含生命周期、最大输入 / 输出 token 和能力字段。

图：本站根据 Claude 官方文档：Model IDs and versioning 整理的示意图

一、当前模型的 ID

官方 Models overview（2026-11-05）的对比表里，四个当前模型是：

官方还建议：不确定用哪个，大多数工作负载先从 Opus 5.5 开始；要求很高的推理和长程智能体任务，或在更高 effort 下 Opus 5.5 的评测仍不够时，用 Fable 5.1。表里另外还给了每个模型的延迟档位、定价、默认 effort、可靠知识截止时间（均为 2026 年 6 月）和最早退役日期，这些请直接看官方页面，本文不抄价格。

怎么写：

python
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",   # 直接填 Claude API ID
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

二、各平台的写法不一样

官方 Model IDs and versioning 页面说明了其他平台的格式：

• Amazon Bedrock： 4.6 代及之后是 anthropic.claude-{name}-{major}[-{minor}]，例如 anthropic.claude-opus-5-5（Models overview 表里的写法）；官方说 Claude Opus 4.6 是最后一个带 -v1 后缀的 Bedrock 模型 ID（anthropic.claude-opus-4-6-v1）；4.6 之前的模型是 anthropic.claude-sonnet-4-5-20250929-v1:0 这种带日期和版本后缀的格式。
• Google Cloud 上的 Claude（Google 托管）： 4.6 代及之后格式与 Claude API 相同；4.6 之前的模型用 @ 分隔日期，例如 claude-haiku-4-5@20251001。
• Microsoft Foundry： 默认使用 Claude API 的模型 ID（有别名时用别名），你发送的是部署名。
• Claude Platform on AWS： 用 Claude API 的模型 ID，不是 Bedrock 风格的 ID。

换平台时，最容易出错的是把 Bedrock 的 ID 拿去 Claude API 用，或反过来。

三、别名和停用

官方的几点说明：

• 别名只是便利指针：官方说 Claude API 上只有 4.6 之前的模型有这种别名；4.6 代及之后的无日期 ID 本身就是固定快照。想要稳定行为，写完整的、固定的 ID。
• 每个模型 ID，不论带不带日期，都有自己独立的弃用和退役时间表。官方的 Models overview 里「Retirement」一行是 Anthropic 对其运营平台的承诺，合作伙伴运营的平台自己定日期。
• 模型权重对一个 ID 是固定的，但周边的服务基础设施（请求路由、安全分类器、采样逻辑等）可能变化。官方说这偶尔会带来细微的行为差异，如果你在一个原本稳定的 ID 上发现意外变化，基础设施更新是最可能的原因。

四、用 Models API 查可用模型

官方说，可以用 Models API 以编程方式查询模型能力和 token 上限。请求：

bash
curl https://api.anthropic.com/v1/models \
    -H 'anthropic-version: 2026-10-21' \
    -H "Authorization: Bearer $ANTHROPIC_API_KEY"

（这是官方 List Models 页面的示例，认证头写法见顶部 verify 提示，不同官方页面的示例认证头不一致，请以对应页面为准。）

查询参数：

• limit：每页数量，默认 20，范围 1 到 1000；
• after_id / before_id：分页游标；
• lifecycle：按生命周期过滤，可取 active、deprecated、retired，最多 3 个。不传时只返回 active 和 deprecated 的模型，retired 只有明确请求才会出现。

另外官方列了可选请求头 anthropic-workspace-id：仅在你的凭据能操作多个工作区时才需要。

返回的每个模型（ModelInfo）有这些字段：

• id、display_name、created_at；
• lifecycle：active（可用、对新用户开放、没有退役计划）、deprecated（对已有权限的组织仍可调用，但即将退役，不再对新用户开放）、retired（不再可用，调用会失败，仍在目录里作为历史记录）；
• deprecated_at、retires_at：弃用与退役时间，可能为 null；
• max_input_tokens、max_tokens；
• line：模型所属系列，如 haiku、sonnet、opus、fable、mythos，或 null。官方提醒：做模型选择器分组时读 line，不要从 id 推断，Anthropic 以后可能增加新的系列；
• capabilities：能力对象，每项都有 supported 布尔值。

capabilities 里有用的几项（官方列出）： batch（是否支持批量接口）、citations（是否支持引用）、image_input、pdf_input、structured_outputs、effort、thinking、context_management，以及 server_tools（是否接受联网搜索和代码执行工具）。

几个官方特别提醒的细节：

• server_tools.web_search.supported 和 server_tools.code_execution.supported 为 true，表示模型接受该工具的至少一个版本，不一定每个版本；
• 即使工具被支持，你的组织设置仍可能让请求失败，比如管理员关闭了联网搜索；
• thinking.types.disabled.supported 为 false 表示模型会以 400 拒绝 thinking: {type: "disabled"}。官方举例：Sonnet 5.5 的这一项报告为 false。

用法举例：发请求前，程序先查某个模型 capabilities.citations.supported，再决定是否开启引用，见 /guides/claude-api-citations；联网搜索与代码执行见 /guides/claude-api-web-search-tool 和 /guides/claude-api-code-execution-tool。

图：本站根据官方文档整理的示意图

常见问题

Q：Python SDK 里有对应方法吗？

官方 API reference 的 models/list 方法对应这个接口；SDK 里的具体写法请看官方 SDK 文档，本文不替它写。

Q：我用的老模型 ID 还能用多久？

看 Models API 返回的 lifecycle、deprecated_at、retires_at，以及官方的 Model deprecations 页面。已退役的模型请求会失败。

Q：怎么从旧模型迁移？

官方 Models overview 里提到：如果你在 Opus 5 或更早的版本上，可以看官方的 Opus 5.5 迁移指南。

Q：调用报 404 或模型不存在？

先用 Models API 确认该 ID 你的账号下是否可用，再检查拼写和平台格式。其他 API 报错见 /guides/claude-api-error-429-rate-limit 与 /guides/claude-api-error-529-overloaded。

相关教程

• /guides/claude-models-compare：Claude 各模型对比
• /guides/claude-api-python-quickstart：Python 快速上手
• /guides/claude-api-key-console：API Key 与 Console

参考资料

• Claude 开发者平台文档：Models overview — https://platform.claude.com/docs/en/models/overview
• Claude 开发者平台文档：Model IDs and versioning — https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions
• Claude 开发者平台文档：List Models — https://platform.claude.com/docs/en/api/models/list