Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
本指南涵盖迁移 Messages API 代码。如果您使用 Claude 托管代理，则除了更新模型名称外无需任何更改。
使用 Claude API 技能自动化您的迁移。 在 Claude Code 中，运行 /claude-api migrate 来调用捆绑的 Claude API 技能。它适用于本页面上的任何目标模型：
/claude-api migrate this project to claude-opus-4-8该技能会在您的代码库中应用模型 ID 替换，并根据需要针对您的目标模型应用破坏性参数更改、预填充替换和 effort 校准，然后生成一份需要手动验证的项目清单。在编辑任何文件之前，它会要求您确认迁移范围（整个工作目录、子目录或特定文件列表）。该技能还会检测 Amazon Bedrock、Google Cloud、Claude Platform on AWS 和 Microsoft Foundry 客户端，并针对每个平台调整模型 ID 格式和功能更改。
Claude Mythos 5 是 Claude Mythos Preview（仅限邀请的研究预览版）的访问受限后继模型。如需具有相同能力的正式发布模型，请参阅 Claude Fable 5。
迁移基本上是即插即用的。Claude Mythos 5 使用与 Claude Mythos Preview 相同的 Messages API 和相同的工具使用模式，并且由于两个模型使用相同的分词器，令牌计数大致不变。需要检查的关键更改是不再可用的功能（在下一节中列出）和思考输出。
有关 Claude Mythos Preview 的停用时间表，请参阅模型弃用。
model = "claude-mythos-preview" # Before
model = "claude-mythos-5" # After扩展思考和思考令牌预算： 手动扩展思考（thinking: {type: "enabled", budget_tokens: N}）在 claude-mythos-5 上不受支持，并返回 400 错误。自适应思考始终开启：模型会在每个请求中决定何时思考以及思考多少，无需任何 thinking 配置。thinking: {type: "disabled"} 会返回错误。budget_tokens 没有直接的替代品：思考是自适应的，而 effort 参数是一个独立的输出级控制，而不是思考预算。
之前（Claude Mythos Preview）：
client.messages.create(
model="claude-mythos-preview",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)之后（Claude Mythos 5）：
client.messages.create(
model="claude-mythos-5",
max_tokens=16000,
messages=[{"role": "user", "content": "..."}],
)助手预填充： 预填充助手消息在 claude-mythos-5 上不受支持，并返回 400 错误，与 Claude Mythos Preview 上相同。请改用系统提示指令。
思考输出： 在 claude-mythos-5 上，原始思维链永远不会被返回，但当 thinking.display 设置为 summarized 时，思考块仍然携带可读的摘要文本。在同一模型上继续对话时，请原样传回思考块。请参阅 Claude Fable 5 和 Claude Mythos 5 上的思考输出。
claude-mythos-5 使用与 claude-mythos-preview 相同的分词器（随 Claude Opus 4.7 引入的分词器）。从 claude-mythos-preview 迁移时，令牌计数大致不变。与 Claude Opus 4.7 之前的模型相比，相同的内容可能会被分词为大约多 30% 的令牌，具体因内容和工作负载形态而异。
与 claude-mythos-preview 相比，/v1/messages/count_tokens 为 claude-mythos-5 返回的值大致不变。请在您自己的工作负载上重新建立成本和延迟基线。
claude-mythos-preview 更新为 claude-mythos-5。thinking: {type: "enabled", budget_tokens: N}）。自适应思考始终开启，无需 thinking 字段。thinking: {type: "disabled"} 配置。在 claude-mythos-5 上禁用思考会返回错误。budget_tokens。它没有直接的替代品：思考是自适应的，而 effort 参数是一个独立的输出级控制，而不是思考预算。thinking 字段的代码仅将其视为显示文本，并在同一模型上继续时原样传回思考块。thinking.display 在 claude-mythos-5 上默认为 "omitted"，与 Claude Mythos Preview 上相同；设置 display: "summarized" 以接收可读的摘要。请参阅 Claude Fable 5 和 Claude Mythos 5 上的思考输出。thinking 和 redacted_thinking 块。来自 claude-mythos-5 的思考块与生成它们的模型绑定，除 Claude Fable 5 和 Claude Mythos 5 之外的模型会静默忽略它们。剥离可使跨模型请求保持最小化和一致性。claude-mythos-preview 迁移时，令牌计数大致不变。Claude Fable 5 是 Anthropic 能力最强的广泛发布模型，在 Claude API、Claude Platform on AWS、Amazon Bedrock、Google Cloud 和 Microsoft Foundry 上正式可用。
迁移基本上是即插即用的。Claude Fable 5 使用与 Claude Opus 4.8 相同的 Messages API 和相同的工具使用模式。它默认支持相同的 1M 令牌上下文窗口和相同的 128k 最大输出令牌。由于两个模型使用相同的分词器，令牌计数大致不变。
需要检查的关键更改是始终开启的自适应思考、思考输出、安全分类器拒绝和定价。迁移之前涵盖定价和数据保留；更改内容涵盖其余部分。
Claude Fable 5 的定价为每百万输入令牌 10 美元、每百万输出令牌 50 美元，而 Claude Opus 4.8 为 5 美元和 25 美元。详情请参阅 Claude 定价。
Claude Fable 5 要求 30 天数据保留，并且在零数据保留（ZDR）安排下不可用；它被指定为受涵盖模型（Covered Model）。在 Claude API 上，来自数据保留配置不满足此要求的组织的请求会返回 400 invalid_request_error。拥有 ZDR 安排的组织应联系其 Anthropic 客户团队讨论数据保留配置；Claude Opus 4.8 在 ZDR 下仍然可用。或者，您可以按工作区配置数据保留。30 天数据保留要求适用于提供 Claude Fable 5 的每个平台；有关各平台的详细信息，请参阅特定模型的数据保留要求。
如果您的代码在 Claude Opus 4.7 或更早版本上，请先应用从 Claude Opus 4.7 迁移到 Claude Opus 4.8，对于早于 Claude Opus 4.7 的模型，还需应用 Claude Opus 4.7 迁移步骤。这些章节涵盖了本节不再重复的破坏性更改（采样参数被拒绝、手动扩展思考被拒绝、预填充被移除、新分词器）。
model = "claude-opus-4-8" # Before
model = "claude-fable-5" # After本节中的项目描述了在您替换模型 ID 后值得检查的 API 和行为差异。
自适应思考始终开启： 自适应思考是 claude-fable-5 上唯一的思考模式。模型会在每个请求中决定何时思考以及思考多少，无需任何 thinking 配置。thinking: {type: "disabled"} 会返回错误。使用 effort 参数来控制思考深度。
需要检查的行为变化：在 Claude Opus 4.8 上，没有 thinking 字段的请求在不思考的情况下运行；在 claude-fable-5 上，这些相同的请求会以自适应思考运行。max_tokens 仍然是总输出（思考加响应文本）的硬性限制，因此对于在 Claude Opus 4.8 上不使用思考运行的工作负载，请重新审视该值。请参阅成本控制。
之前（Claude Opus 4.8）：
client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "..."}],
)之后（Claude Fable 5）：
client.messages.create(
model="claude-fable-5",
max_tokens=16000,
output_config={"effort": "high"},
messages=[{"role": "user", "content": "..."}],
)扩展思考和思考预算（不变）： 手动扩展思考（thinking: {type: "enabled", budget_tokens: N}）在 claude-fable-5 上不受支持，并返回 400 错误，与 Claude Opus 4.8 上相同。budget_tokens 没有直接的替代品：思考是自适应的，而 effort 参数是一个独立的输出级控制，而不是思考预算。
助手预填充（不变）： 预填充助手消息在 claude-fable-5 上不受支持，并返回 400 错误，与 Claude Opus 4.8 上相同。请改用系统提示指令。
思考输出： 在 claude-fable-5 上，原始思维链永远不会被返回，但当 thinking.display 设置为 summarized 时，思考块仍然携带可读的摘要文本。在同一模型上继续对话时，请原样传回思考块。请参阅 Claude Fable 5 和 Claude Mythos 5 上的思考输出。
安全分类器和 refusal 停止原因： claude-fable-5 会对请求以及响应生成过程运行安全分类器。当分类器拒绝请求时，Messages API 会以成功的 HTTP 200 响应返回 stop_reason: "refusal"，而不是错误。stop_details.category 字段报告触发了哪个分类器，类别包括 "cyber"、"bio" 和 "reasoning_extraction"，当拒绝不对应任何命名类别时为 null。完整集合请参阅拒绝类别表。
对于在生成任何输出之前被拒绝的请求，您无需为其输入令牌付费。当分类器在流式传输中途触发时，输入和已流式传输的输出会被计费；请丢弃部分输出。
要自动在另一个模型上重新运行被拒绝的请求，请传递可选的 fallbacks 参数，该参数在 Claude API 和 Claude Platform on AWS 上处于测试阶段。该参数在 Message Batches API 或 Amazon Bedrock、Google Cloud 和 Microsoft Foundry 上不可用；在这三个平台上，请在客户端运行重试或使用 SDK 拒绝回退中间件。请参阅处理停止原因。
从 high effort 开始： effort 参数的默认值仍为 high。在 Claude Opus 4.8 上，对于编码和高自主性工作的建议是显式设置 xhigh。在 claude-fable-5 上，对于大多数任务使用 high 作为默认值，并将 xhigh 保留给对能力最敏感的工作负载。在 claude-fable-5 上，较低的 effort 设置仍然表现良好，并且通常超过先前模型上 xhigh 的性能。如果任务能完成但耗时超过必要，请降低 effort。请参阅为 Claude Fable 5 编写提示。
更低的提示缓存最小值： claude-fable-5 上可缓存提示的最小长度为 512 个令牌，低于 Claude Opus 4.8 上的 1,024 个令牌。在 Claude Opus 4.8 上因太短而无法缓存的提示现在可以创建缓存条目，无需更改代码。在 Amazon Bedrock 上，claude-fable-5 的最小值为 1,024 个令牌。有关各模型的最小值，请参阅提示缓存。
claude-fable-5 要求 30 天数据保留，否则在 Claude API 上会返回 400 invalid_request_error。请参阅特定模型的数据保留要求。claude-opus-4-8 更新为 claude-fable-5。thinking: {type: "disabled"} 配置。在 claude-fable-5 上禁用思考会返回错误，并且没有 thinking 字段的请求会以自适应思考运行。claude-fable-5 上仍然不受支持。thinking 字段的代码仅将其视为显示文本，并在同一模型上继续时原样传回思考块。thinking.display 在 claude-fable-5 上默认为 "omitted"，与 Claude Opus 4.8 上相同；设置 display: "summarized" 以接收可读的摘要。请参阅 Claude Fable 5 和 Claude Mythos 5 上的思考输出。thinking 和 redacted_thinking 块。来自 claude-fable-5 的思考块与生成它们的模型绑定，除 Claude Fable 5 和 Claude Mythos 5 之外的模型会静默忽略它们。剥离可使跨模型请求保持最小化和一致性。例外情况是兑换回退额度，这需要按照该功能的确切规则回显请求体。stop_reason: "refusal" 并读取 stop_details.category 字段。要自动在另一个模型上重新运行被拒绝的请求，请考虑可选的 fallbacks 参数（测试版）。请参阅处理停止原因。effort 设置。对于大多数任务从 high 开始，包括在 Claude Opus 4.8 上以 xhigh 运行的工作负载。claude-opus-4-8 迁移时，令牌计数大致不变；每令牌定价有所不同。Claude Opus 4.8 专为复杂的代理式编码和企业工作而构建。它建立在 Claude Opus 4.7 的基础之上。
Claude Opus 4.8 在现有的 Claude Opus 4.7 提示和评估上应该具有强大的开箱即用性能。对于已经在 Claude Opus 4.7 上运行的代码，没有破坏性的 API 更改。它支持与 Claude Opus 4.7 相同的功能集，包括 1M 令牌上下文窗口、128k 最大输出令牌、自适应思考、提示缓存、批处理、Files API、PDF 支持、视觉，以及完整的服务器端和客户端工具集。它还新增了对话中途系统消息，并公开记录了拒绝停止详情。
如果您的代码在 Claude Opus 4.6 或更早版本上，在升级到 Claude Opus 4.8 之前，还请应用下面的 Claude Opus 4.7 迁移步骤。这些步骤包括仅靠 4.8 升级无法涵盖的破坏性更改（采样参数被拒绝、手动扩展思考被拒绝、新分词器）。
# Opus 迁移
model = "claude-opus-4-7" # Before
model = "claude-opus-4-8" # After这些不是破坏性更改。在 Claude Opus 4.7 上运行的代码在 Claude Opus 4.8 上可以继续无需更改地运行。以下项目描述了在您替换模型 ID 后值得检查的行为差异。
采样参数（不变）： 将 temperature、top_p 或 top_k 设置为非默认值会在 Claude Opus 4.8 上返回 400 错误，与 Claude Opus 4.7 上相同。SDK 请求类型仍然定义这些字段以与早期模型兼容，因此设置它们的代码可以通过类型检查，但 API 会在服务器端拒绝该请求。如果您在迁移到 Opus 4.7 时已移除这些参数，则无需进一步更改。
Effort 默认值为 high： Claude Opus 4.8 上 effort 参数的默认值在所有界面（包括 Claude Code 和 Messages API）上均为 high。如果您已经显式设置了 effort，您的设置不会改变。对于编码和高自主性工作，请显式设置 xhigh。请根据您的延迟和成本预算重新评估您的 effort 设置。
1M 上下文窗口是默认值： Claude Opus 4.8 默认提供完整的 1M 令牌上下文窗口，无需 beta 标头，也没有长上下文溢价。如果您的客户端为了与旧模型兼容而传递上下文窗口 beta 标头，您可以在 Claude Opus 4.8 上将其移除。
对话中途系统消息： Claude Opus 4.8 接受在 messages 数组中紧跟用户轮次之后的 role: "system" 消息（受放置规则约束）。对于从一开始就适用的指令，请使用顶层 system 字段。早期模型（包括 Claude Opus 4.7）会以 400 错误拒绝 messages 中的 role: "system"。如果您维护着为更新指令而重建完整消息历史的代码路径，您可以简化它们并保留早期轮次上的提示缓存命中。
拒绝停止详情： 拒绝响应上的 stop_details 对象（自 Claude Opus 4.7 起可用）现已公开记录。当模型拒绝请求时，除了现有的 refusal 停止原因外，它还会标识拒绝的类别。无需 beta 标头，也无法选择退出。请参阅处理停止原因。
更低的提示缓存最小值： Claude Opus 4.8 上可缓存提示的最小长度为 1,024 个令牌，低于 Claude Opus 4.7。在 Claude Opus 4.7 上因太短而无法缓存的提示现在可以创建缓存条目，无需更改代码。有关各模型的最小值，请参阅提示缓存。
Effort 级别重新校准： 与 Claude Opus 4.7 相比，Claude Opus 4.8 上每个 effort 级别背后的令牌分配有所变化：medium 允许稍多的思考，high 稍少，而 xhigh 则大幅增加。如果您针对 Claude Opus 4.7 的成本或延迟调优了某个 effort 级别，请在调整之前先在同一级别重新建立基线。请参阅 Effort。
claude-opus-4-7 更新为 claude-opus-4-8（或更新别名）。effort 设置。所有界面上的默认值均为 high；对于编码和高自主性工作，请显式设置 xhigh。stop_details（自 Claude Opus 4.7 起可用；现已公开记录）。Claude Opus 4.7 具有高度自主性，在长周期代理式工作、知识工作、视觉任务和记忆任务上表现出色。
Claude Opus 4.7 在现有的 Claude Opus 4.6 提示和评估上应该具有强大的开箱即用性能，且每百万令牌定价同为 $5 / $25，但在迁移时有一些值得了解的行为和 API 更改。它支持与 Claude Opus 4.6 相同的功能集，包括：
# Opus 迁移
model = "claude-opus-4-6" # Before
model = "claude-opus-4-7" # After扩展思考已移除： thinking: {type: "enabled", budget_tokens: N} 在 Claude Opus 4.7 或更高版本的模型上不再受支持，并返回 400 错误。请切换到自适应思考（thinking: {type: "adaptive"}），并使用 effort 参数来控制思考深度。自适应思考在 Claude Opus 4.7 上默认关闭：没有 thinking 字段的请求在不思考的情况下运行，与 Opus 4.6 的行为一致。请显式设置 thinking: {type: "adaptive"} 以启用它。
之前（Claude Opus 4.6）：
client.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)之后（Claude Opus 4.7）：
client.messages.create(
model="claude-opus-4-7",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)自适应思考可以通过提示进行引导。有关在模型思考过度或不足时进行调优的指导，请参阅校准 effort 和思考深度。
采样参数已移除： 在 Claude Opus 4.7 上将 temperature、top_p 或 top_k 设置为任何非默认值会返回 400 错误。最安全的迁移路径是从请求负载中完全省略这些参数。在 Claude Opus 4.7 上，提示是引导模型行为的推荐方式。如果您曾使用 temperature = 0 来实现确定性，请注意它在先前的模型上也从未保证过完全相同的输出。
思考内容默认省略： 在 Claude Opus 4.7 上，思考块仍然出现在响应流中，但除非您显式选择启用，否则其 thinking 字段为空。这是相对于 Claude Opus 4.6 的一个静默更改，后者的默认行为是返回摘要思考文本。要在 Claude Opus 4.7 上恢复摘要思考内容，请将 thinking.display 设置为 "summarized"：
thinking = {
"type": "adaptive",
"display": "summarized",
}Claude Opus 4.7 上的默认值为 "omitted"。如果您的产品向用户流式传输推理过程，新的默认值会表现为输出开始前的长时间停顿；设置 display: "summarized" 以恢复思考期间的可见进度。详情请参阅扩展思考。
更新的令牌计数： Claude Opus 4.7 使用新的分词器，这有助于其在广泛任务上的性能提升。与先前的模型相比，新分词器在处理文本时可能使用大约 1 倍到 1.35 倍的令牌（最多约多 35%，因内容而异）。
/v1/messages/count_tokens 为 Claude Opus 4.7 返回的令牌数量将与 Claude Opus 4.6 不同。令牌效率可能因工作负载形态而异。
提示干预、task_budget 和 effort 可以帮助控制成本并确保适当的令牌使用。这些控制可能会以模型智能为代价。请更新您的 max_tokens 参数以提供额外的余量，包括压缩触发器。Claude Opus 4.7 以标准 API 定价提供 1M 上下文窗口，无长上下文溢价。
预填充移除（从 Opus 4.6 延续）： 在 Claude Opus 4.7 上预填充助手消息会返回 400 错误。请改用结构化输出、系统提示指令或 output_config.format。
effort 参数允许您在 Claude 的智能与令牌消耗之间进行权衡，以能力换取更快的速度和更低的成本。对于编码和代理式用例，请从新的 xhigh effort 级别开始，对于大多数对智能敏感的用例，请至少使用 high effort。尝试其他 effort 级别以进一步调优令牌使用和智能：
max： 最大 effort 在某些用例中可以带来性能提升，但随着令牌使用量的增加可能会出现收益递减。此设置有时也容易出现过度思考。请针对对智能要求高的任务测试最大 effort。xhigh（新）： 超高 effort 是大多数编码和代理式用例的最佳设置。high： 此设置在令牌使用和智能之间取得平衡。对于大多数对智能敏感的用例，请至少使用 high effort。medium： 适用于需要减少令牌使用同时以智能为代价的成本敏感型用例。low： 保留给简短、范围明确的任务以及对延迟敏感但对智能不敏感的工作负载。对于此模型，effort 比以往任何 Opus 模型都更重要。升级时请积极尝试。
Claude Opus 4.7 与 Claude Opus 4.6 相比有若干行为差异，这些差异不属于 API 破坏性变更，但可能需要更新提示或移除脚手架。
响应长度因用例而异： Claude Opus 4.7 会根据其判断的任务复杂程度来校准响应长度，而不是默认采用固定的详细程度。这通常意味着对简单查询给出更短的回答，而对开放式分析给出更长的回答。
如果您的产品依赖于特定风格或详细程度的输出，您可能需要调整提示。例如，要降低详细程度，可以添加："提供简洁、聚焦的响应。跳过非必要的上下文，并尽量减少示例。"如果您发现特定类型的过度解释，请在提示中添加有针对性的指令来防止它们。
展示 Claude 如何以适当简洁程度进行沟通的正面示例，往往比告诉模型不要做什么的负面示例或指令更有效。
更字面的指令遵循： Claude Opus 4.7 比 Claude Opus 4.6 更字面、更明确地解释提示，尤其是在较低的 effort 级别下。它不会悄悄地将一个项目的指令泛化到另一个项目，也不会推断您没有提出的请求。这种字面性的好处是精确性和更少的反复。对于具有精心调优的提示、结构化提取以及需要可预测行为的管道的 API 用例，它通常表现更好。对提示和框架进行审查可能对迁移到 Claude Opus 4.7 特别有帮助。
更直接的语气： 与任何新模型一样，长篇写作的文风可能会发生变化。Claude Opus 4.7 更直接、更有主见，相比 Claude Opus 4.6 更温暖的风格，其措辞中的认同性表达更少，表情符号也更少。如果您的产品依赖于特定的语气，请针对新基线重新评估风格提示。
代理轨迹中内置的进度更新： Claude Opus 4.7 在长代理轨迹中为用户提供更规律、更高质量的更新。如果您添加了脚手架来强制生成中间状态消息（"每 3 次工具调用后，总结进度"），请尝试将其移除。如果您发现 Claude Opus 4.7 面向用户的更新的长度或内容与您的用例不够匹配，请在提示中明确描述这些更新应该是什么样子，并提供示例。
默认生成更少的子代理： Claude Opus 4.7 默认倾向于生成更少的子代理。不过，这种行为可以通过提示来引导；请为 Claude Opus 4.7 提供关于何时需要子代理的明确指导。
更严格的 effort 校准： 与 Claude Opus 4.6 相比有显著变化，Claude Opus 4.7 严格遵守 effort 级别，尤其是在低端。在 low 和 medium 级别下，模型会将其工作范围限定在所要求的内容上，而不是超额完成。
这对延迟和成本有利，但在以 low effort 运行中等复杂度任务时，存在思考不足的风险。如果您在复杂问题上观察到浅层推理，请将 effort 提高到 high 或 xhigh，而不是通过提示来规避。
如果您出于延迟考虑需要将 effort 保持在 low，请添加有针对性的指导："此任务涉及多步推理。在响应之前仔细思考问题。"请参阅 Claude Opus 4.7 的推荐 effort 级别。
默认更少的工具调用： Claude Opus 4.7 倾向于比 Claude Opus 4.6 更少地使用工具，而更多地使用推理。在大多数情况下，这会产生更好的结果。
要增加工具使用，请提高 effort 设置。high 或 xhigh effort 设置在代理搜索和编码中会显示出明显更多的工具使用。您也可以调整提示，明确指示模型何时以及如何正确使用其工具。
实时网络安全防护： Claude Opus 4.7 新增的功能，涉及被禁止或高风险主题的请求可能会导致拒绝。对于渗透测试、漏洞研究或红队演练等合法的安全工作，请申请 Cyber Verification Program 以请求降低限制。有关背景信息，请参阅防护措施、警告和申诉。
高分辨率图像支持： Claude Opus 4.7 是第一个支持高分辨率图像的 Claude 模型。最大图像分辨率为长边 2576 像素，高于之前模型的 1568 像素。这为视觉密集型工作负载带来了提升，对于计算机使用、截图理解和文档分析尤其有价值。
高分辨率支持是自动的，不需要 beta 标头或客户端选择启用。需要规划的两件事：
max_tokens 和成本预期，或者如果您不需要额外的保真度，请在发送前进行降采样。详情请参阅 Claude Opus 4.7 上的高分辨率图像支持。
这些不是必需的，但会改善您的体验：
重新评估 max_tokens： 由于相同的文本在 Claude Opus 4.7 上会产生更高的令牌数，请更新您的 max_tokens 参数以提供额外的余量，包括压缩触发器。提示干预、task_budget 和 effort 可以帮助控制成本并确保适当的令牌使用。
审核令牌计数预期： 任何在客户端估算令牌或假设固定令牌与字符比率的代码路径都应针对 Claude Opus 4.7 重新测试。使用令牌计数端点进行验证。
采用任务预算（beta）： Claude Opus 4.7 引入了任务预算。这些预算让您可以告知 Claude 它在整个代理循环中有多少令牌可用，包括思考、工具调用、工具结果和最终输出。模型会看到一个实时倒计时，并利用它来确定工作优先级，并在预算消耗时优雅地完成任务。要使用此功能，请设置 beta 标头 task-budgets-2026-03-13 并将以下内容添加到您的输出配置中：
output_config = {
"effort": "high",
"task_budget": {"type": "tokens", "total": 128000},
}您可能需要针对您的用例试验不同的任务预算。如果给模型的任务预算过于严格，它可能会不够彻底地完成任务，并将其预算作为约束条件加以引用。
对于质量比速度更重要的开放式代理任务，不要设置任务预算。将任务预算保留给需要模型将其工作范围限定在令牌配额内的工作负载。任务预算的最小值为 20k 令牌。
任务预算不是硬性上限；它是模型知晓的一个建议。它与 max_tokens 不同：
task_budget： 整个代理循环的建议性上限。模型可以看到它并用它来调节自己的节奏。max_tokens： 对生成令牌的每个请求的硬性上限。它不会传递给模型，因此模型不知道它。当您希望模型自我调节时使用 task_budget，并使用 max_tokens 作为限制使用量的硬性上限。
在 max 或 xhigh effort 下设置较大的 max_tokens： 如果您以 max 或 xhigh effort 运行 Claude Opus 4.7，请设置较大的最大输出令牌预算，以便模型有空间在其子代理和工具调用中进行思考和行动。从 64k 令牌开始，然后据此调整。
如果不需要高分辨率，请对图像进行降采样： Claude Opus 4.7 支持最高 2576px / 3.75MP 的图像。高分辨率图像使用更多令牌。如果不需要额外的图像保真度，请在发送给 Claude 之前对图像进行降采样，以避免令牌使用量增加。请参阅图像与视觉。
claude-opus-4-6 更新为 claude-opus-4-7（或更新别名）。temperature、top_p 和 top_k。thinking: {type: "enabled", budget_tokens: N} 替换为 thinking: {type: "adaptive"} 加上 effort 参数。max_tokens 以适应更新后的分词方式。xhigh 或 max effort，请将 max_tokens 提高到至少 64k 作为起点。如果您要从 Claude Opus 4.5、Opus 4.1（已弃用）或更早的模型直接迁移到 Claude Opus 4.7，请应用所有 Opus 4.7 变更，以及本节中在 Opus 4.5 和 Opus 4.7 之间生效的累积变更。如果您从 Opus 4.6 迁移，则只需要 Opus 4.7 部分。
# Opus 迁移
model = "claude-opus-4-5" # Before
model = "claude-opus-4-7" # After预填充移除已在上面的 Opus 4.7 破坏性变更中介绍。
工具参数引号处理： Claude Opus 4.6 及更高版本的模型在工具调用参数中可能产生略有不同的 JSON 字符串转义（例如，对 Unicode 转义或正斜杠转义的不同处理）。如果您将工具调用 input 作为原始字符串解析而不是使用 JSON 解析器，请验证您的解析逻辑。标准 JSON 解析器（如 json.loads() 或 JSON.parse()）会自动处理这些差异。
这些变更可改善您在 Opus 4.7 上的体验。标记为**（Opus 4.7 上必需）**的项目在 Opus 4.6 发布时是可选建议，但现在是强制性的；其余项目仍为建议。
迁移到自适应思考（Opus 4.7 上必需）： thinking: {type: "enabled", budget_tokens: N} 在 Claude Opus 4.7 上会返回 400 错误。切换到 thinking: {type: "adaptive"} 并使用 effort 参数来控制思考深度。请参阅自适应思考。
response = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 32000},
betas=["interleaved-thinking-2025-05-14"],
messages=[{"role": "user", "content": "Your prompt here"}],
)请注意，此迁移还会从 client.beta.messages.create 移至 client.messages.create。自适应思考和 effort 是正式发布（GA）的功能，不需要 beta SDK 命名空间或任何 beta 标头。
移除 effort beta 标头： effort 参数现已正式发布。从您的请求中移除 betas=["effort-2025-11-24"]。
移除细粒度工具流式传输 beta 标头： 细粒度工具流式传输现已正式发布。从您的请求中移除 betas=["fine-grained-tool-streaming-2025-05-14"]。
移除交错思考 beta 标头： 自适应思考会在 Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 上自动启用交错思考。从您的请求中移除 betas=["interleaved-thinking-2025-05-14"]。该标头在使用手动扩展思考的 Sonnet 4.6 上仍然有效，但手动模式已被弃用。
迁移到 output_config.format： 如果使用结构化输出，请将 output_format={...} 更新为 output_config={"format": {...}}。旧参数仍然有效，但已被弃用，并将在未来的模型版本中移除。
如果您要从 Opus 4.1（已弃用）或更早的模型直接迁移到 Claude Opus 4.7，请应用本指南顶部的 Claude Opus 4.7 变更和上述累积变更，以及本节中的额外变更。
# 来自 Opus 4.1
model = "claude-opus-4-1-20250805" # Before
model = "claude-opus-4-7" # After
# 来自 Sonnet 3.7
model = "claude-3-7-sonnet-20250219" # Before
model = "claude-opus-4-7" # After移除采样参数
从 Claude 3.x 模型迁移时，这是一个破坏性变更。
从 Claude Opus 4.7 开始，将 temperature、top_p 或 top_k 设置为任何非默认值都将返回 400 错误。最安全的迁移路径是从请求中完全省略这些参数，并使用提示来引导模型的行为。如果您之前使用 temperature = 0 来实现确定性，请注意它从未保证过相同的输出。
# 之前 - 在 Claude 4+ 模型中会报错
response = client.messages.create(
model="claude-3-7-sonnet-20250219",
temperature=0.7,
top_p=0.9, # Non-default sampling params return 400 on Opus 4.7
# ...
)
# 之后
response = client.messages.create(
model="claude-opus-4-7",
# ...
)更新工具版本
从 Claude 3.x 模型迁移时，这是一个破坏性变更。
更新到最新的工具版本。移除所有使用 undo_edit 命令的代码。
# 之前
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
# 之后
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]处理 refusal 停止原因
更新您的应用程序以处理 refusal 停止原因：
response = client.messages.create(...)
if response.stop_reason == "refusal":
# 适当处理拒绝响应
pass处理 model_context_window_exceeded 停止原因
当生成因达到上下文窗口限制而非请求的 max_tokens 限制而停止时，Claude 4.5+ 模型会返回 model_context_window_exceeded 停止原因。更新您的应用程序以处理这个新的停止原因：
response = client.messages.create(...)
if response.stop_reason == "model_context_window_exceeded":
# 适当处理上下文窗口限制
pass验证工具参数处理（尾随换行符）
Claude 4.5+ 模型会保留工具调用字符串参数中的尾随换行符，而之前这些换行符会被去除。如果您的工具依赖于对工具调用参数的精确字符串匹配，请验证您的逻辑能正确处理尾随换行符。
针对行为变化更新您的提示
Claude 4+ 模型具有更简洁、直接的沟通风格，并且需要明确的指示。请查阅提示最佳实践以获取优化指导。
token-efficient-tools-2025-02-19 和 output-128k-2025-02-19。所有 Claude 4+ 模型都内置了令牌高效的工具使用，这些标头没有任何效果。claude-opus-4-7output_config.formatthinking: {type: "enabled", budget_tokens: N} 替换为 thinking: {type: "adaptive"} 加上 effort 参数（在 Opus 4.7 上返回 400）effort-2025-11-24 beta 标头（effort 现已正式发布）fine-grained-tool-streaming-2025-05-14 beta 标头interleaved-thinking-2025-05-14 beta 标头（自适应思考会自动启用交错思考）output_format 迁移到 output_config.format（如适用）temperature、top_p 和 top_k（非默认值在 Opus 4.7 上返回 400）text_editor_20250728、code_execution_20260521）refusal 停止原因model_context_window_exceeded 停止原因token-efficient-tools-2025-02-19、output-128k-2025-02-19）Claude Sonnet 5 在 Claude 模型系列中提供了速度与智能的最佳组合。它建立在 Claude Sonnet 4.6 的基础之上。
Claude Sonnet 5 是 Claude Sonnet 4.6 的直接替代升级，价格相同，为每百万令牌 $3 / $15（2026 年 8 月 31 日前的优惠价为每百万令牌 $2 / $10；请参阅定价）。对于已在 Claude Sonnet 4.6 上运行的代码，有两个破坏性 API 变更：手动扩展思考（thinking: {type: "enabled", budget_tokens: N}）和设置为非默认值的采样参数（temperature、top_p、top_k）不再被接受，并返回 400 错误。请改用自适应思考和 effort 参数。Claude Sonnet 5 支持与 Claude Sonnet 4.6 相同的功能集，包括 1M 令牌上下文窗口、自适应思考、提示缓存、批处理、Files API、PDF 支持、视觉，以及完整的服务器端和客户端工具集。Claude Sonnet 5 不支持 Priority Tier。Claude Sonnet 5 还使用了新的分词器。
如果您的代码在 Claude Sonnet 4.5 或更早版本上运行，在升级到 Claude Sonnet 5 之前，还请应用 Claude Sonnet 4.6 迁移步骤。这些步骤包括仅靠 Sonnet 5 升级无法涵盖的破坏性变更（拒绝助手消息预填充、工具参数 JSON 转义差异）。
# Sonnet 迁移
model = "claude-sonnet-4-6" # Before
model = "claude-sonnet-5" # After以下列表中的第 4 项和第 5 项是破坏性变更。max_tokens 仍然是总输出（思考加响应文本）的硬性限制，因此对于在 Claude Sonnet 4.6 上不使用思考运行的工作负载，请重新审视该值。
新分词器： Claude Sonnet 5 使用新的分词器。相同的输入文本产生的令牌数比 Claude Sonnet 4.6 多约 30%。确切的增幅取决于内容。请求、响应和流式传输事件保持相同的结构，不需要更改代码，但您以令牌为单位衡量或预算的任何内容都会发生变化：相同文本的 usage 字段和令牌计数结果会更高，1M 令牌上下文窗口能容纳的文本更少，为 Claude Sonnet 4.6 调优的 max_tokens 限制可能会截断等效的输出。每令牌定价不变，因此等效请求的成本可能会有所不同。请针对 Claude Sonnet 5 重新运行令牌计数，而不是重用针对早期模型测得的计数。
128k 最大输出令牌（不变）： Claude Sonnet 5 支持最多 128k 输出令牌，与 Claude Sonnet 4.6 相同。现有的 max_tokens 值仍然有效。在确定其大小时请考虑新的分词器。
助手消息预填充（不变）： 在 Claude Sonnet 5 上预填充助手消息会返回 400 错误，与 Claude Sonnet 4.6 相同。如果您在迁移到 Claude Sonnet 4.6 时已移除预填充，则无需进一步更改。请改用结构化输出、系统提示指令或 output_config.format。
默认启用自适应思考： 在 Claude Sonnet 4.6 上，没有 thinking 字段的请求在不使用思考的情况下运行；在 Claude Sonnet 5 上，相同的请求会使用自适应思考运行。要关闭思考，请传递 thinking: {type: "disabled"}。手动扩展思考（thinking: {type: "enabled", budget_tokens: N}）不受支持，并返回 400 错误。使用 effort 参数（默认为 high）来控制思考深度。
Claude Sonnet 5 默认启用自适应思考。此处明确显示 thinking 字段是为了设置 display: "summarized"；如果您省略 thinking，Claude Sonnet 5 默认会从响应中省略思考内容。有关各模型的默认值，请参阅自适应思考。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "high"},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# 响应包含摘要化的思考块和文本块
for block in response.content:
match block.type:
case "thinking":
print(f"\nThinking summary: {block.thinking}")
case "text":
print(f"\nResponse: {block.text}")移除采样参数： 设置为非默认值的采样参数（temperature、top_p、top_k）不被接受，并返回 400 错误。
网络安全防护： Claude Sonnet 5 是第一个具有实时网络安全防护的 Sonnet 级别模型。涉及被禁止或高风险网络安全主题的请求可能会被拒绝。拒绝会以成功的 HTTP 200 响应返回，带有 stop_reason: "refusal"，而不是错误。有关背景信息，请参阅防护措施、警告和申诉。
claude-sonnet-4-6 更新为 claude-sonnet-5。max_tokens 限制，并在有用的情况下将其提高到 128k 最大值（与 Claude Sonnet 4.6 相同）。thinking: {type: "enabled", budget_tokens: N} 配置（返回 400 错误）。自适应思考默认启用；传递 {type: "disabled"} 来关闭它，或使用 effort 参数来控制深度。temperature、top_p 和 top_k 参数（它们在 Claude Sonnet 5 上返回 400 错误）。stop_reason: "refusal" 的处理。max_tokens。Claude Sonnet 4.6 将强大的智能与快速的性能相结合，具有改进的代理搜索能力，并且在与网络搜索或网络获取一起使用时可免费使用代码执行。它非常适合日常编码、分析和内容任务。
有关功能的完整概述，请参阅模型概述。
Sonnet 4.6 的定价为每百万输入令牌 $3，每百万输出令牌 $15。详情请参阅 Claude 定价。
更新您的模型名称：
# 来自 Sonnet 4.5
model = "claude-sonnet-4-5" # Before
model = "claude-sonnet-4-6" # After不再支持预填充助手消息
从 Sonnet 4.5 或更早版本迁移时，这是一个破坏性变更。
在 Sonnet 4.6 上预填充助手消息会返回 400 错误。请改用结构化输出、系统提示指令或 output_config.format。
常见的预填充用例及迁移方法：
控制输出格式（强制 JSON/YAML 输出）：对于分类任务，使用结构化输出或带有枚举字段的工具。
消除开场白（移除"以下是……"之类的短语）：在系统提示中添加直接指令："直接响应，不要有开场白。不要以'以下是……'、'基于……'等短语开头。"
避免不当拒绝： Claude 现在在适当拒绝方面表现得更好。在用户消息中进行清晰的提示而无需预填充应该就足够了。
续写（恢复被中断的响应）：将续写移至用户消息："您之前的响应被中断了，以 [previous_response] 结尾。请从中断处继续。"
上下文补充 / 角色一致性（在长对话中刷新上下文）：将之前作为预填充助手提醒的内容改为注入到用户轮次中。
工具参数 JSON 转义可能有所不同
从 Sonnet 4.5 或更早版本迁移时，这是一个破坏性变更。
工具参数中的 JSON 字符串转义可能与之前的模型不同。标准 JSON 解析器会自动处理这一点，但基于自定义字符串的解析可能需要更新。
更新采样参数
从 Claude 3.x 模型迁移时，这是一个破坏性变更。
只使用 temperature 或 top_p 之一，不要同时使用两者。
更新工具版本
从 Claude 3.x 模型迁移时，这是一个破坏性变更。
更新到最新的工具版本（text_editor_20250728、code_execution_20260521）。移除所有使用 undo_edit 命令的代码。
处理 refusal 停止原因
更新您的应用程序以处理 refusal 停止原因。
针对行为变化更新您的提示
Claude 4 模型具有更简洁、直接的沟通风格。请查阅提示最佳实践以获取优化指导。
fine-grained-tool-streaming-2025-05-14 beta 标头： 细粒度工具流式传输现已在 Sonnet 4.6 上正式发布，不再需要 beta 标头。output_format 迁移到 output_config.format： output_format 参数已被弃用。请改用 output_config.format。请考虑从 Sonnet 4.5 迁移到 Sonnet 4.6，后者以相同的价格提供更高的智能。
Sonnet 4.6 的默认 effort 级别为 high，而 Sonnet 4.5 没有 effort 参数。在从 Sonnet 4.5 迁移到 Sonnet 4.6 时，请考虑调整 effort 参数。如果未显式设置，使用默认 effort 级别可能会导致更高的延迟。
如果您在 Sonnet 4.5 上没有使用扩展思考，您可以在 Sonnet 4.6 上继续不使用它。您应该显式地将 effort 设置为适合您用例的级别。在 low effort 且禁用思考的情况下，相对于未使用扩展思考的 Sonnet 4.5，您可以预期获得相似或更好的性能。
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=8192,
output_config={"effort": "low"},
messages=[{"role": "user", "content": "Your prompt here"}],
)如果您在 Sonnet 4.5 上使用带有 budget_tokens 的扩展思考，它在 Sonnet 4.6 上仍然可用，但已被弃用。请迁移到使用 effort 参数的自适应思考。
自适应思考是 Sonnet 4.6 上 budget_tokens 的推荐替代方案。它特别适合以下工作负载模式：
high effort 开始。如果延迟或令牌使用量是一个问题，请降低到 medium。使用自适应思考时，请在您的任务上评估 medium 和 high effort。合适的级别取决于您的工作负载在质量、延迟和令牌使用量之间的权衡。
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=64000,
thinking={"type": "adaptive"},
output_config={"effort": "medium"},
messages=[{"role": "user", "content": "Your prompt here"}],
)如果您在使用自适应思考时发现行为不一致或质量下降，请先尝试降低 effort 设置，或使用 max_tokens 作为硬性限制。带有 budget_tokens 的扩展思考在 Sonnet 4.6 上仍然可用，但已被弃用且不再推荐。
如果您在迁移期间需要暂时保留 budget_tokens，约 16k 令牌的预算可以为更困难的问题提供余量，同时避免令牌使用量失控的风险。此配置已被弃用，并将在未来的模型版本中移除。
对于代理式编码、前端设计、工具密集型工作流和复杂的企业工作流，请从 medium effort 开始。如果您发现延迟过高，请考虑将 effort 降低到 low。如果您需要更高的智能，请考虑将 effort 提高到 high 或迁移到 Opus 4.7。
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=16384,
thinking={"type": "enabled", "budget_tokens": 16384},
output_config={"effort": "medium"},
betas=["interleaved-thinking-2025-05-14"],
messages=[{"role": "user", "content": "Your prompt here"}],
)对于聊天、内容生成、搜索、分类和其他非编码任务，请从带有扩展思考的 low effort 开始。如果您需要更深入的推理，请将 effort 提高到 medium。
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=8192,
thinking={"type": "enabled", "budget_tokens": 16384},
output_config={"effort": "low"},
betas=["interleaved-thinking-2025-05-14"],
messages=[{"role": "user", "content": "Your prompt here"}],
)claude-sonnet-4-6output_config.formattext_editor_20250728、code_execution_20260521）；不支持旧版本（如果从 3.x 迁移）undo_edit 命令的代码（如适用）temperature 或 top_p 之一，不能同时使用（如果从 3.x 迁移）refusal 停止原因fine-grained-tool-streaming-2025-05-14 beta 标头（现已正式发布）output_format 迁移到 output_config.formatthinking: {type: "enabled", budget_tokens: N} 迁移到带有 effort 参数的 thinking: {type: "adaptive"}（budget_tokens 已被弃用，并将在未来版本中移除）Claude Sonnet 4.5 将强大的智能与快速的性能相结合，非常适合日常编码、分析和内容任务。
有关功能的完整概述，请参阅模型概述。
Sonnet 4.5 的定价为每百万输入令牌 3 美元，每百万输出令牌 15 美元。详情请参阅 Claude 定价。
更新您的模型名称：
# 从 Sonnet 3.7 开始
model = "claude-3-7-sonnet-20250219" # Before
model = "claude-sonnet-4-5-20250929" # After这些重大变更适用于从 Claude 3.x Sonnet 模型迁移的情况。
更新采样参数
从 Claude 3.x 模型迁移时，这是一项重大变更。
仅使用 temperature 或 top_p 之一，不能同时使用。
更新工具版本
从 Claude 3.x 模型迁移时，这是一项重大变更。
更新到最新的工具版本（text_editor_20250728、code_execution_20260521）。移除任何使用 undo_edit 命令的代码。
处理 refusal 停止原因
更新您的应用程序以处理 refusal 停止原因。
针对行为变化更新您的提示
Claude 4 模型具有更简洁、直接的沟通风格。请查阅提示最佳实践以获取优化指导。
claude-sonnet-4-5-20250929text_editor_20250728、code_execution_20260521）；不支持旧版本（如果从 3.x 迁移）undo_edit 命令的代码（如适用）temperature 或 top_p 之一，不能同时使用（如果从 3.x 迁移）refusal 停止原因Claude Haiku 4.5 是最快且最智能的 Haiku 模型，具有接近前沿的性能，为交互式应用程序和大批量处理提供高端模型质量。
有关功能的完整概述，请参阅模型概述。
Haiku 4.5 的定价为每百万输入令牌 1 美元，每百万输出令牌 5 美元。详情请参阅 Claude 定价。
更新您的模型名称：
# 来自 Haiku 3.5
model = "claude-3-5-haiku-20241022" # Before
model = "claude-haiku-4-5-20251001" # After查看新的速率限制： Haiku 4.5 的速率限制与 Haiku 3.5 是分开的。详情请参阅速率限制文档。
要在编码和推理任务上获得显著的性能提升，请考虑使用 thinking: {type: "enabled", budget_tokens: N} 启用扩展思考。
探索新功能： 请参阅模型概述，了解上下文感知、更大的输出容量（64k 令牌）、更高的智能和更快的速度等详细信息。
这些重大变更适用于从 Claude 3.x Haiku 模型迁移的情况。
更新采样参数
从 Claude 3.x 模型迁移时，这是一项重大变更。
仅使用 temperature 或 top_p 之一，不能同时使用。
更新工具版本
从 Claude 3.x 模型迁移时，这是一项重大变更。
更新到最新的工具版本（text_editor_20250728、code_execution_20250825）。移除任何使用 undo_edit 命令的代码。
处理 refusal 停止原因
更新您的应用程序以处理 refusal 停止原因。
针对行为变化更新您的提示
Claude 4 模型具有更简洁、直接的沟通风格。请查阅提示最佳实践以获取优化指导。
claude-haiku-4-5-20251001text_editor_20250728、code_execution_20250825）；不支持旧版本undo_edit 命令的代码（如适用）temperature 或 top_p 之一，不能同时使用refusal 停止原因Was this page helpful?