按消息设置 effort

使用系统消息在对话中途更改 effort 级别，同时保留提示缓存。

按消息更改 effort 会为对话的后续轮次设置新的 effort 级别，而不会更改请求的顶层值，因此缓存的前缀仍然匹配。

更改 effort 级别

要在对话中途更改级别：

在 messages 中添加一条 role: "system" 消息，将 content 留空，并在 output_config.effort 中设置新的 effort 级别。
发送 mid-conversation-output-config-2026-07-01 beta 标头。
保持顶层值不变。

以下示例将顶层值保持为 high，并在一次常规的后续交互中降至 low：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    output_config={"effort": "high"},
    messages=[
        {
            "role": "user",
            "content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
        },
        {
            "role": "assistant",
            "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
        },
        # 仅含 effort 的系统消息：新级别从下一个用户轮次开始生效。
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
    betas=["mid-conversation-output-config-2026-07-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

该消息的位置决定新级别何时开始生效：

紧跟在包含新输入的 user 轮次之后：Claude 对该轮次的回复会使用新的级别。
在其他任何位置，例如前面示例中那样位于一个 assistant 轮次与下一个 user 轮次之间：新的级别从下一个包含新输入的 user 轮次开始生效。

仅包含 tool_result 块的 user 轮次不算新输入。

新的级别会一直有效，直到后续消息更改它为止。

请将该消息放在您已发送的所有内容之后，并在后续请求中将其保留在原位。不要将其插入到您已发送的轮次之前，之后也不要移动或删除它。在支持 preserved thinking（保留思考）的模型上，任何此类更改都会使该消息之后 assistant 轮次中的思考块失效。API 如何处理无效块说明了接下来会发生什么。

如果它与一条有内容的 system 消息相邻，则两条消息都必须遵循对话中途系统消息的放置规则。

使用 Amazon Bedrock InvokeModel API 时，请在请求体的 anthropic_beta 数组中发送 beta 值，而不是通过标头发送。有关在该平台上支持按消息设置 effort 的模型，请参阅 Bedrock 上的对话中系统消息。

错误

如果没有 beta 标头，按消息设置的 output_config 会返回 400 错误：messages.N.output_config: Extra inputs are not permitted，其中 N 是该 system 消息在 messages 中的索引。
如果带有 beta 标头，不支持按消息设置 effort 的模型（例如 Claude Fable 5）会返回 400 错误：output_config.effort requires a model that supports per-turn effort; this model does not。在 Amazon Bedrock 上，这些模型以及 Claude Opus 5 则会返回 Extra inputs are not permitted。
在使用 thinking: {"type": "between_tools"} 的 Claude Sonnet 5.5 以及使用 thinking: {"type": "disabled"} 的 Claude Haiku 5.5 上，effort 级别无法在对话中途更改。在这些情况下，带有新级别的按消息设置的 output_config.effort 会返回 400 错误。要为每个轮次设置不同的 effort，请使用 adaptive thinking（自适应思考）。

按消息设置还是顶层设置 effort

相比在请求之间更改顶层值，建议优先使用按消息设置 effort。按消息更改不会影响其之前的所有内容，因此缓存的前缀仍然匹配。更改顶层值会使缓存重新开始。在 Claude Fable 5.1 上，更改顶层值对模型的引导效果也不太可靠。模型之前的回复是在先前级别下生成的，它往往会与这些回复保持一致。

可用性

按消息设置 effort

状态: Beta
API: Messages API
Managed Agents 不支持
Beta 请求头: 需要
模型: Claude Fable 5.2、Fable 5.1
Claude Mythos 5.2、Mythos 5.1
Claude Opus 5.5、Opus 5
Claude Sonnet 5.5
Claude Haiku 5.5

更改 effort 级别

错误

按消息设置还是顶层设置 effort

可用性

更改 effort 级别

错误

按消息设置还是顶层设置 effort

可用性