---
title: 逐訊息 effort
url: https://platform.claude.com/docs/zh-TW/build-with-claude/effort-per-message
description: 使用系統訊息在對話進行途中變更 effort 等級，同時保留提示快取。
featureMetadata:
  status: beta
  betaHeader: mid-conversation-output-config-2026-07-01
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-haiku-5-5
  supportedPlatforms:
    Claude API: beta
    Amazon Bedrock: beta
    Amazon Bedrock (bedrock-runtime):
      availability: beta
      note: 在請求主體的 `anthropic_beta` 陣列中傳送 beta 值。
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed): beta
    Claude Models on Google Cloud (Google managed): beta
    Microsoft Foundry: beta
---

逐訊息的 effort 變更會為對話後續的回合設定新的 effort 等級，而不會變更請求的頂層值，因此快取的前綴仍然相符。

## 變更 effort 等級

若要在對話進行途中變更等級：

1. 在 `messages` 中新增一則 `role: "system"` 訊息，其 `content` 為空，並在 `output_config.effort` 中設定新的 [effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 等級。
2. 傳送 `mid-conversation-output-config-2026-07-01` [beta 標頭](https://platform.claude.com/docs/zh-TW/api/beta-headers)。
3. 頂層的值保持不變。

以下範例將頂層的值維持在 `high`，並針對例行的後續追問降至 `low`：

<CodeGroup>
  ```bash cURL
  # 僅含 effort 的系統訊息：新等級將從下一個使用者回合起生效。
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: mid-conversation-output-config-2026-07-01" \
    -H "content-type: application/json" \
    -d '{
      "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."},
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."}
      ]
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta mid-conversation-output-config-2026-07-01 <<'YAML'
  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.
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await 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 (const block of response.content) {
    if (block.type === "text") {
      console.log(block.text);
    }
  }
  ```

  ```csharp C#
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var response = await client.Beta.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeFable5_1,
      MaxTokens = 4096,
      OutputConfig = new() { Effort = Effort.High },
      Messages =
      [
          new BetaUserMessageParam { Content = "Plan a migration from SQLite to PostgreSQL in three short steps." },
          new BetaAssistantMessageParam { Content = "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." },
          // 僅含 effort 的系統訊息：新的等級將自下一個使用者回合起生效。
          new BetaSystemMessageParam
          {
              Content = new([]),
              OutputConfig = new() { Effort = BetaSystemMessageOutputConfigEffort.Low },
          },
          new BetaUserMessageParam { Content = "Summarize the plan in one sentence." },
      ],
      Betas = [AnthropicBeta.MidConversationOutputConfig2026_07_01],
  });

  foreach (var block in response.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeFable5_1,
  	MaxTokens: 4096,
  	OutputConfig: anthropic.BetaOutputConfigParam{
  		Effort: anthropic.BetaOutputConfigEffortHigh,
  	},
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Plan a migration from SQLite to PostgreSQL in three short steps.")),
  		{OfAssistant: &anthropic.BetaAssistantMessageParam{
  			Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")},
  		}},
  		// 僅含 effort 的系統訊息：新等級自下一個使用者回合起生效。
  		anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{
  			Effort: anthropic.BetaSystemMessageOutputConfigEffortLow,
  		}),
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize the plan in one sentence.")),
  	},
  	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMidConversationOutputConfig2026_07_01},
  })
  if err != nil {
  	log.Fatal(err)
  }

  for _, block := range response.Content {
  	if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  import com.anthropic.models.beta.AnthropicBeta;
  import com.anthropic.models.beta.messages.BetaMessage;
  import com.anthropic.models.beta.messages.BetaOutputConfig;
  import com.anthropic.models.beta.messages.BetaSystemMessageOutputConfig;
  import com.anthropic.models.beta.messages.BetaSystemMessageParam;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_FABLE_5_1)
          .maxTokens(4096L)
          .addBeta(AnthropicBeta.MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01)
          .outputConfig(BetaOutputConfig.builder()
              .effort(BetaOutputConfig.Effort.HIGH)
              .build())
          .addUserMessage("Plan a migration from SQLite to PostgreSQL in three short steps.")
          .addAssistantMessage("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")
          // 僅含 effort 的系統訊息：新層級將從下一個使用者回合開始生效。
          .addMessage(BetaSystemMessageParam.builder()
              .contentOfBlocks(List.of())
              .outputConfig(BetaSystemMessageOutputConfig.builder()
                  .effort(BetaSystemMessageOutputConfig.Effort.LOW)
                  .build())
              .build())
          .addUserMessage("Summarize the plan in one sentence.")
          .build();

      BetaMessage response = client.beta().messages().create(params);
      response.content().stream()
          .flatMap(block -> block.text().stream())
          .forEach(textBlock -> IO.println(textBlock.text()));
  }
  ```

  ```php PHP
  use Anthropic\Beta\AnthropicBeta;
  use Anthropic\Beta\Messages\BetaMessageParam;
  use Anthropic\Beta\Messages\BetaOutputConfig;
  use Anthropic\Beta\Messages\BetaSystemMessageOutputConfig;
  use Anthropic\Beta\Messages\BetaTextBlock;
  use Anthropic\Client;
  use Anthropic\Messages\Model;

  $client = new Client();

  $response = $client->beta->messages->create(
      model: Model::CLAUDE_FABLE_5_1,
      maxTokens: 4096,
      outputConfig: BetaOutputConfig::with(effort: 'high'),
      messages: [
          BetaMessageParam::with(role: 'user', content: 'Plan a migration from SQLite to PostgreSQL in three short steps.'),
          BetaMessageParam::with(role: 'assistant', content: '1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.'),
          // 僅含 effort 的系統訊息：新等級自下一個使用者回合起生效。
          BetaMessageParam::with(
              role: 'system',
              content: [],
              outputConfig: BetaSystemMessageOutputConfig::with(effort: 'low'),
          ),
          BetaMessageParam::with(role: 'user', content: 'Summarize the plan in one sentence.'),
      ],
      betas: [AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01],
  );

  foreach ($response->content as $block) {
      if ($block instanceof BetaTextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.beta.messages.create(
    model: Anthropic::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: [Anthropic::AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01]
  )

  response.content.each do |block|
    case block
    when Anthropic::Beta::BetaTextBlock
      puts block.text
    end
  end
  ```
</CodeGroup>

訊息的位置決定新等級何時開始生效：

* 緊接在包含新輸入的 `user` 回合之後：Claude 對該回合的回覆會使用新的等級。
* 在其他任何位置，例如前面範例中位於 `assistant` 回合與下一個 `user` 回合之間：新的等級會從下一個包含新輸入的 `user` 回合開始生效。

僅包含 `tool_result` 區塊的 `user` 回合不算是新輸入。

新的等級會持續生效，直到後續的訊息變更它為止。

請將該訊息放在您已傳送的所有內容之後，並在後續請求中將其保留在原位。不要將它插入到您已傳送的回合之前，之後也不要移動或移除它。在支援 [preserved thinking（保留思考）](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking)的模型上，上述任何一種變更都會使該訊息之後 `assistant` 回合中的思考區塊失效。[API 如何處理無效區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#mismatch-behavior)說明了接下來會發生的情況。

若該訊息緊鄰一則含有內容的 `system` 訊息，兩則訊息都必須遵循[對話中系統訊息的放置規則](https://platform.claude.com/docs/zh-TW/build-with-claude/mid-conversation-system-messages#limitations)。

使用 Amazon Bedrock InvokeModel API 時，請在請求主體的 `anthropic_beta` 陣列中傳送 beta 值，而非使用標頭。關於在該平台上支援逐訊息 effort 的模型，請參閱 [Bedrock 上的對話中系統訊息](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-amazon-bedrock-legacy#mid-conversation-system-messages-on-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，請使用自適應思考。

## 逐訊息或頂層 effort

建議優先使用逐訊息 effort，而非在請求之間[變更頂層的值](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#top-level-effort-on-the-next-request)。逐訊息的變更會讓其之前的所有內容保持不變，因此快取的前綴仍然相符。頂層的變更則會重新開始快取。在 Claude Fable 5.1 上，頂層的變更引導模型的可靠性也較低。模型先前的回覆是以先前的等級撰寫的，而模型傾向於與這些回覆保持一致。

## 可用性

逐訊息 effort在特定模型上處於 Beta 階段。

### API 支援

#### [Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/working-with-messages)

* 可用性：可用

| 狀態               | 雲端平台                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | 模型                                                                                                                                                                                                                                                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Beta             | Claude API, [Amazon Bedrock](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock), [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.1](https://platform.claude.com/docs/zh-TW/models/fable-5-1/overview), [Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/overview)                                                                                                                                                                               |
| Beta<sup>1</sup> | [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-amazon-bedrock-legacy)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [Claude Fable 5.2](https://platform.claude.com/docs/zh-TW/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/zh-TW/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/zh-TW/models/fable-5-1/overview), [Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/overview) |
| Beta             | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry)                                                                                                      | [Claude Fable 5.2](https://platform.claude.com/docs/zh-TW/models/fable-5-2/overview), [Claude Opus 5](https://platform.claude.com/docs/zh-TW/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/overview)     |
| Beta             | Claude API, [Amazon Bedrock](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry)                                                                                                                                                                                                                                                     | [Claude Mythos 5.1](https://platform.claude.com/docs/zh-TW/models/mythos-5-1/overview)                                                                                                                                                                                                                                                                 |
| Beta             | Claude API, [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry)                                                                                                                                                                                           | [Claude Mythos 5.2](https://platform.claude.com/docs/zh-TW/models/mythos-5-2/overview)                                                                                                                                                                                                                                                                 |

1. 在請求主體的 `anthropic_beta` 陣列中傳送 beta 值。

#### [Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview)

* 可用性：不可用
* 用法：請改為透過覆寫代理的模型設定，為工作階段設定 effort。

### 必要的 Beta 標頭

[Beta 標頭概覽](https://platform.claude.com/docs/zh-TW/api/beta-headers)

Beta 標頭可讓您在實驗性功能與新模型能力成為標準 API 的一部分之前搶先存取。

* `mid-conversation-output-config-2026-07-01`