---
title: Claude Sonnet 5.5 遷移指南
url: https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide
description: 透過本遷移指南，從較早的 Sonnet 模型或 Claude Haiku 4.5 切換至 Claude Sonnet 5.5。啟用 Claude Sonnet 5.5 的指引涵蓋會傳回錯誤的設定、思考方面的變更，以及針對每個起始模型的檢查清單。
---

本指南列出從 Claude Sonnet 5、Claude Sonnet 4.6、Claude Sonnet 4.5、Claude Sonnet 4、Claude 3.7 Sonnet 或 Claude Haiku 4.5 遷移至 Claude Sonnet 5.5 所需的程式碼變更。請先閱讀前兩個章節，然後往下閱讀至您目前模型對應的章節。[遷移檢查清單](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migration-checklist)依起始模型列出了每一項變更。

<Note>
  本指南涵蓋遷移 [Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/working-with-messages) 程式碼的相關內容。如果您使用 [Claude Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview)，除了更新模型名稱之外，不需要進行任何其他變更。
</Note>

<Tip>
  **使用 Claude API skill 自動化您的遷移。** 在 Claude Code 中，執行 `/claude-api migrate` 以呼叫內建的 [Claude API skill](https://platform.claude.com/docs/zh-TW/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)。它適用於以任何目前的 Claude 模型作為目標：

  讓 Claude Code 為您遷移程式碼

  ```text
  /claude-api migrate 將此專案遷移至 claude-sonnet-5-5
  ```

  此 skill 會在您的整個程式碼庫中套用模型 ID 替換，並視需要處理破壞性參數變更、prefill（預填）替換，以及針對目標模型的 effort（努力程度）校準，然後產生一份需要手動驗證的項目清單。在編輯任何檔案之前，它會請您確認遷移範圍（整個工作目錄、某個子目錄，或特定的檔案清單）。此 skill 也會偵測 Amazon Bedrock 與 Claude Platform on AWS 用戶端，並針對這些平台調整模型 ID 格式與功能變更。
</Tip>

Claude Sonnet 5.5 的價格與 Claude Sonnet 5 相同，唯一的例外是提示快取讀取，其費用為每百萬 token 0.10 美元，為 Claude Sonnet 5 費率的一半。請參閱 [Claude 定價](https://platform.claude.com/docs/zh-TW/about-claude/pricing)。關於其上下文視窗與輸出限制，請參閱 [Claude Sonnet 5.5 模型頁面](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/overview)。關於功能與提示撰寫，請參閱 [Claude Sonnet 5.5 的新功能](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/whats-new-sonnet-5-5#feature-support)與[為 Claude Sonnet 5.5 撰寫提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5)。

## 向 Claude Sonnet 5.5 傳送請求

此請求可直接在 Claude Sonnet 5.5 上運作。它設定了「effort level」（投入程度等級），而各 SDK 分頁會依區塊類型讀取回覆。它省略了五項會傳回 400 錯誤的設定：[思考預算](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes)、[取樣參數](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes)、[助理預填](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45)、[強制工具選擇](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#forced-tool-use)，以及 [`thinking: {"type": "disabled"}`](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)。

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 4096,
      "messages": [{
        "role": "user",
        "content": "Analyze the trade-offs between microservices and monolithic architectures"
      }],
      "output_config": {
        "effort": "medium"
      }
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-sonnet-5-5 \
    --max-tokens 4096 \
    --output-config '{effort: medium}' \
    --message '{role: user, content: "Analyze the trade-offs between microservices and monolithic architectures"}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=4096,
      messages=[
          {
              "role": "user",
              "content": "Analyze the trade-offs between microservices and monolithic architectures",
          }
      ],
      output_config={"effort": "medium"},
  )

  print(f"Stop reason: {response.stop_reason}")
  for block in response.content:
      if block.type == "text":
          print(block.text)
  ```

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

  const response = await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Analyze the trade-offs between microservices and monolithic architectures"
      }
    ],
    output_config: {
      effort: "medium"
    }
  });

  console.log(`Stop reason: ${response.stop_reason}`);
  const textBlock = response.content.find(
    (block): block is Anthropic.TextBlock => block.type === "text"
  );
  console.log(textBlock?.text);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 4096,
      Messages = [
          new() {
              Role = Role.User,
              Content = "Analyze the trade-offs between microservices and monolithic architectures"
          }
      ],
      OutputConfig = new OutputConfig
      {
          Effort = Effort.Medium
      }
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine($"Stop reason: {message.StopReason?.Raw()}");
  foreach (var block in message.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

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

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the trade-offs between microservices and monolithic architectures")),
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortMedium,
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println("Stop reason:", response.StopReason)
  for _, block := range response.Content {
  	if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  import com.anthropic.models.messages.OutputConfig;

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

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(4096L)
          .addUserMessage("Analyze the trade-offs between microservices and monolithic architectures")
          .outputConfig(OutputConfig.builder()
              .effort(OutputConfig.Effort.MEDIUM)
              .build())
          .build();

      Message response = client.messages().create(params);
      response.stopReason().ifPresent(reason -> IO.println("Stop reason: " + reason));
      response.content().stream()
          .flatMap(block -> block.text().stream())
          .forEach(textBlock -> IO.println(textBlock.text()));
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 4096,
      messages: [
          ['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
      ],
      model: 'claude-sonnet-5-5',
      outputConfig: ['effort' => 'medium'],
  );

  echo "Stop reason: {$message->stopReason}", PHP_EOL;
  foreach ($message->content as $block) {
      if ($block->type === 'text') {
          echo $block->text, PHP_EOL;
      }
  }
  ```

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

  message = client.messages.create(
    model: "claude-sonnet-5-5",
    max_tokens: 4096,
    messages: [
      { role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" }
    ],
    output_config: {
      effort: "medium"
    }
  )

  puts "Stop reason: #{message.stop_reason}"
  message.content.each do |block|
    puts block.text if block.type == :text
  end
  ```
</CodeGroup>

## 預設會執行思考

在 Claude Sonnet 5.5 上，未包含 `thinking` 欄位的請求會以[「adaptive thinking」（自適應思考）](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)執行，`thinking: {"type": "adaptive"}` 亦同。在 Claude Sonnet 4.6 及更早的模型以及 Claude Haiku 4.5 上，這類請求會在不進行思考的情況下執行。若要繼續在不進行前置思考的情況下執行，請參閱[關閉前置思考](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)。

| 模型                                   | 未包含 `thinking` 欄位時的思考 | 接受的 `thinking.type` 值                      | 預設 `display`   |
| ------------------------------------ | --------------------- | ------------------------------------------ | -------------- |
| Claude Sonnet 5.5                    | 開啟                    | `"adaptive"`、`"between_tools"`             | `"omitted"`    |
| Claude Sonnet 5                      | 開啟                    | `"adaptive"`、`"disabled"`                  | `"omitted"`    |
| Claude Sonnet 4.6                    | 關閉                    | `"adaptive"`、`"disabled"`、`"enabled"`（已棄用） | `"summarized"` |
| Claude Sonnet 4.5 與 Claude Haiku 4.5 | 關閉                    | `"disabled"`、`"enabled"`                   | `"summarized"` |

### 在回應中處理思考

原本在不進行思考的情況下執行的程式碼需要以下全部三項。來自 Claude Sonnet 5 的程式碼可能已具備前兩項。

* **依 `type` 讀取內容區塊。** 回應可能以 `thinking` 區塊開頭，因此讀取 `content[0].text` 的程式碼會出錯。
* **在工具使用迴圈中原封不動地傳回 `thinking` 區塊**，包括空的區塊。請參閱[保留思考區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#preserving-thinking-blocks)。
* **重新檢視 `max_tokens`。** 它同時涵蓋思考與文字，且思考 token 會以輸出 token 計費。請參閱[成本控制](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-steering-and-cost#cost-control)。

思考文字預設會被省略。`thinking` 區塊送達時會帶有空的 `thinking` 欄位和一個 `signature`。若要取得可讀的摘要，請設定 `display: "summarized"`，這是 Claude Sonnet 4.6 及更早模型以及 Claude Haiku 4.5 上的預設值。請參閱[控制思考顯示](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#controlling-thinking-display)。

### 關閉前置思考

若要在 Claude Sonnet 5.5 上關閉前置思考，請傳送 `thinking: {"type": "between_tools"}`。這是最低的思考設定。它在工具呼叫之間的進度更新仍會以帶有摘要文字的 `thinking` 區塊傳回。沒有工具時，回應只包含文字。Claude Sonnet 5 則改用 `thinking: {"type": "disabled"}` 關閉思考，而更早的模型預設不進行思考。在 Claude Sonnet 5.5 上，`disabled` 會傳回 400 `invalid_request_error`：

```text wrap
To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.
```

`between_tools` 可在所有提供 Claude Sonnet 5.5 的平台上運作，無需 beta 標頭。它在 `low`、`medium` 與 `high` effort 下皆可接受。在 `xhigh` 或 `max` 下，它會傳回 400 錯誤。若要在這些等級下執行，請使用自適應思考：省略 `thinking` 欄位或傳送 `thinking: {"type": "adaptive"}`。`between_tools` 不接受其他欄位：與其一同傳送的 `display`、`budget_tokens` 或 `block_binding` 都會傳回 400 錯誤。使用[伺服器端備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#server-side-fallback)時，備援至 Claude Sonnet 5 的 `between_tools` 請求會在該模型上以 `thinking: {"type": "disabled"}` 執行。

使用 `between_tools` 時，effort 無法在對話中途變更：與目前生效等級不同的逐訊息 `output_config.effort` 會傳回 400 錯誤。若要逐輪變更 effort，請使用自適應思考。關於提示撰寫指引，請參閱[在不進行前置思考的情況下執行](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking)。

之前（Claude Sonnet 5）：

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5",
      "max_tokens": 16000,
      "thinking": {"type": "disabled"},
      "output_config": {"effort": "xhigh"},
      "messages": [{"role": "user", "content": "..."}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-sonnet-5 \
    --max-tokens 16000 \
    --thinking '{type: disabled}' \
    --output-config '{effort: xhigh}' \
    --message '{role: user, content: "..."}'
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5",
      max_tokens=16000,
      thinking={"type": "disabled"},
      output_config={"effort": "xhigh"},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 16000,
    thinking: { type: "disabled" },
    output_config: { effort: "xhigh" },
    messages: [{ role: "user", content: "..." }]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigDisabled(),
      OutputConfig = new() { Effort = Effort.Xhigh },
      Messages = [new() { Role = Role.User, Content = "..." }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5,
  	MaxTokens: 16000,
  	Thinking: anthropic.ThinkingConfigParamUnion{
  		OfDisabled: &anthropic.ThinkingConfigDisabledParam{},
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortXhigh,
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5)
      .maxTokens(16000L)
      .thinking(ThinkingConfigDisabled.builder().build())
      .outputConfig(OutputConfig.builder()
          .effort(OutputConfig.Effort.XHIGH)
          .build())
      .addUserMessage("...")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5,
      maxTokens: 16000,
      thinking: ThinkingConfigDisabled::with(),
      outputConfig: OutputConfig::with(effort: Effort::XHIGH),
      messages: [['role' => 'user', 'content' => '...']],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5,
    max_tokens: 16000,
    thinking: Anthropic::ThinkingConfigDisabled.new,
    output_config: { effort: Anthropic::OutputConfig::Effort::XHIGH },
    messages: [{ role: "user", content: "..." }]
  )
  ```
</CodeGroup>

之後（Claude Sonnet 5.5）：

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 16000,
      "thinking": {"type": "between_tools"},
      "output_config": {"effort": "high"},
      "messages": [{"role": "user", "content": "..."}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-sonnet-5-5 \
    --max-tokens 16000 \
    --thinking '{type: between_tools}' \
    --output-config '{effort: high}' \
    --message '{role: user, content: "..."}'
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=16000,
      thinking={"type": "between_tools"},
      output_config={"effort": "high"},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 16000,
    thinking: { type: "between_tools" },
    output_config: { effort: "high" },
    messages: [{ role: "user", content: "..." }]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigBetweenTools(),
      OutputConfig = new() { Effort = Effort.High },
      Messages = [new() { Role = Role.User, Content = "..." }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 16000,
  	Thinking: anthropic.ThinkingConfigParamUnion{
  		OfBetweenTools: &anthropic.ThinkingConfigBetweenToolsParam{},
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortHigh,
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5_5)
      .maxTokens(16000L)
      .thinking(ThinkingConfigBetweenTools.builder().build())
      .outputConfig(OutputConfig.builder()
          .effort(OutputConfig.Effort.HIGH)
          .build())
      .addUserMessage("...")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5_5,
      maxTokens: 16000,
      thinking: ThinkingConfigBetweenTools::with(),
      outputConfig: OutputConfig::with(effort: Effort::HIGH),
      messages: [['role' => 'user', 'content' => '...']],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 16000,
    thinking: Anthropic::ThinkingConfigBetweenTools.new,
    output_config: { effort: Anthropic::OutputConfig::Effort::HIGH },
    messages: [{ role: "user", content: "..." }]
  )
  ```
</CodeGroup>

## 依起始模型的遷移檢查清單

請依序往下處理各組，並在列出您模型的那一組之後停止。若使用 Claude Haiku 4.5，請套用除「Claude Sonnet 4 或更早版本」以外的所有組別，最後以「僅限 Claude Haiku 4.5」結束。

### 所有起始模型

* 將模型 ID 變更為 `claude-sonnet-5-5`。
* [依 `type` 讀取內容區塊](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#thinking-in-responses)，並原封不動地傳回 `thinking` 區塊。
* 若要繼續在不進行前置思考的情況下執行，請在 `high` effort 或以下發送[最低的思考設定](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)。
* 將[強制工具使用](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#forced-tool-use)替換為 `auto` 搭配 strict 工具，或在 Amazon Bedrock 上僅使用 `auto`。
* 保持對話為[僅附加](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#thinking-blocks)。
* 在 Claude API 和 Google Cloud 上，將電腦使用移至[工具集](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#computer-use-toolset)，且不使用 `fine-grained-tool-streaming-2025-05-14` beta 標頭。
* 將 [advisor 工具](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#advisor-tool)與受支援的 advisor 搭配使用，並預期會收到加密的建議。
* 從 `thinking` 區塊讀取[工具呼叫之間的文字](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#text-between-tool-calls)。
* [處理拒絕](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#safety-classifiers-and-fallback)，並設定備援。
* [重新執行您的 effort 掃描](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#recommended-changes)，並重新建立成本基準。

### Claude Sonnet 4.6 或更早版本

* 預期[未包含 `thinking` 欄位的請求會進行思考](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#thinking-on-by-default)，並重新檢視 `max_tokens`。
* 以 effort 等級取代[思考預算](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes)。
* 移除非預設的 `temperature`、`top_p` 和 `top_k` 值。
* 若您會[顯示思考文字](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#thinking-in-responses)，請設定 `display: "summarized"`。
* [重新計算 token](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#other-changes-from-claude-sonnet-4-6)，並重新編列圖片 token 預算。

### Claude Sonnet 4.5 或更早版本

* 取代[助理「prefill」（預填）](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45)。
* 使用標準 JSON 剖析器剖析工具呼叫輸入。
* 在 Amazon Bedrock 上，將電腦使用從 `computer_20250124` 移至 [`computer_20251124`](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#computer-use-toolset)。
* 明確設定 `output_config.effort`。
* 移除任何上下文視窗 beta 標頭。
* 移除 `interleaved-thinking-2025-05-14`，並以 `eager_input_streaming` 取代 `fine-grained-tool-streaming-2025-05-14`。
* 將 `output_format` 移至 `output_config.format`。

### Claude Sonnet 4 或更早版本

* 將[工具版本](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-4-or-earlier)更新為 `text_editor_20250728` 和 `code_execution_20260521`。
* 處理 `refusal` 和 `model_context_window_exceeded` 停止原因。
* 檢查工具字串參數是否有結尾換行字元。
* 移除 `token-efficient-tools-2025-02-19` 和 `output-128k-2025-02-19`。
* 檢閱您的提示。

### 僅限 Claude Haiku 4.5

* 取代 [`claude-haiku-4-5-20251001`](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migrating-from-claude-haiku-4-5) 或其別名。
* 以較高的每 token 價格重新建立成本基準。
* 檢閱在 Claude Haiku 4.5 上因過短而無法快取的提示。

## 從 Claude Sonnet 5 遷移至 Claude Sonnet 5.5

所有起始模型都需要本節中的變更。請將您的模型 ID 替換為 `claude-sonnet-5-5`，此 ID 沒有日期後綴。在其他平台上，請使用[可用性](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/whats-new-sonnet-5-5#availability)下列出的 ID。

### 不支援強制工具使用

本頁上所有較早的模型都接受類型為 `any` 或 `tool` 的 `tool_choice`。Claude Sonnet 5.5 會以 400 錯誤拒絕這兩者，包括在 [token 計數](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)端點上：

```text wrap
tool_choice: type "tool" and "any" are not supported for this model.
```

請傳送 `tool_choice: {"type": "auto"}`，並將工具標記為 `strict: true`，使其輸入符合結構描述。如此一來，模型可以在不呼叫工具的情況下回答，因此請在提示中說明何時使用該工具。[嚴格工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/strict-tool-use)支援 JSON Schema 的子集，且每個物件都需要 `additionalProperties: false`。請參閱 [JSON Schema 限制](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs#json-schema-limitations)。在 Amazon Bedrock 上，Claude Sonnet 5.5 無法使用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)（包括嚴格工具使用）。在該平台上，請傳送不含 `strict` 的 `auto`，在提示中說明何時呼叫工具，並在您的程式碼中驗證工具輸入。

之前（Claude Sonnet 5）：

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5",
      "max_tokens": 1024,
      "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"],
          "additionalProperties": false
        }
      }],
      "tool_choice": {"type": "tool", "name": "get_weather"},
      "messages": [{"role": "user", "content": "What'\''s the weather in Paris?"}]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-5
  max_tokens: 1024
  tools:
    - name: get_weather
      description: Get the current weather in a given location
      input_schema:
        type: object
        properties:
          location:
            type: string
            description: The city and state, e.g. San Francisco, CA
        required: [location]
        additionalProperties: false
  tool_choice:
    type: tool
    name: get_weather
  messages:
    - role: user
      content: What's the weather in Paris?
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5",
      max_tokens=1024,
      tools=tools,
      tool_choice={"type": "tool", "name": "get_weather"},
      messages=[{"role": "user", "content": "What's the weather in Paris?"}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    tools,
    tool_choice: { type: "tool", name: "get_weather" },
    messages: [{ role: "user", content: "What's the weather in Paris?" }]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5,
      MaxTokens = 1024,
      Tools = [.. tools],
      ToolChoice = new ToolChoiceTool { Name = "get_weather" },
      Messages = [new() { Role = Role.User, Content = "What's the weather in Paris?" }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:      anthropic.ModelClaudeSonnet5,
  	MaxTokens:  1024,
  	Tools:      tools,
  	ToolChoice: anthropic.ToolChoiceParamOfTool("get_weather"),
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5)
      .maxTokens(1024L)
      .tools(tools)
      .toolChoice(ToolChoiceTool.of("get_weather"))
      .addUserMessage("What's the weather in Paris?")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5,
      maxTokens: 1024,
      tools: $tools,
      toolChoice: ToolChoiceTool::with(name: 'get_weather'),
      messages: [['role' => 'user', 'content' => "What's the weather in Paris?"]],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5,
    max_tokens: 1024,
    tools: tools,
    tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
    messages: [{ role: "user", content: "What's the weather in Paris?" }]
  )
  ```
</CodeGroup>

之後（Claude Sonnet 5.5）：

<CodeGroup>
  ```bash cURL
  # 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"],
          "additionalProperties": false
        },
        "strict": true
      }],
      "tool_choice": {"type": "auto"},
      "messages": [{
        "role": "user",
        "content": "What'\''s the weather in Paris? Use the get_weather tool."
      }]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-5-5
  max_tokens: 1024
  tools:
    - name: get_weather
      description: Get the current weather in a given location
      input_schema:
        type: object
        properties:
          location:
            type: string
            description: The city and state, e.g. San Francisco, CA
        required: [location]
        additionalProperties: false
      # 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
      strict: true
  tool_choice:
    type: auto
  messages:
    - role: user
      content: What's the weather in Paris? Use the get_weather tool.
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=1024,
      # 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
      tools=[{**tool, "strict": True} for tool in tools],
      tool_choice={"type": "auto"},
      messages=[
          {
              "role": "user",
              "content": "What's the weather in Paris? Use the get_weather tool.",
          }
      ],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    // 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
    tools: tools.map((tool) => ({ ...tool, strict: true })),
    tool_choice: { type: "auto" },
    messages: [
      {
        role: "user",
        content: "What's the weather in Paris? Use the get_weather tool."
      }
    ]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      // 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
      Tools = [.. tools.Select(tool => tool with { Strict = true })],
      ToolChoice = new ToolChoiceAuto(),
      Messages =
      [
          new()
          {
              Role = Role.User,
              Content = "What's the weather in Paris? Use the get_weather tool.",
          },
      ],
  });
  ```

  ```go Go
  // 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
  var strictTools []anthropic.ToolUnionParam
  for _, tool := range tools {
  	strictTool := *tool.OfTool
  	strictTool.Strict = anthropic.Bool(true)
  	strictTools = append(strictTools, anthropic.ToolUnionParam{OfTool: &strictTool})
  }
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:      anthropic.ModelClaudeSonnet5_5,
  	MaxTokens:  1024,
  	Tools:      strictTools,
  	ToolChoice: anthropic.ToolChoiceUnionParam{OfAuto: &anthropic.ToolChoiceAutoParam{}},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(
  			anthropic.NewTextBlock("What's the weather in Paris? Use the get_weather tool."),
  		),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5_5)
      .maxTokens(1024L)
      // 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
      .tools(tools.stream()
          .map(tool -> tool.tool()
              .map(customTool -> customTool.toBuilder().strict(true).build())
              .map(ToolUnion::ofTool)
              .orElse(tool))
          .toList())
      .toolChoice(ToolChoiceAuto.builder().build())
      .addUserMessage("What's the weather in Paris? Use the get_weather tool.")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5_5,
      maxTokens: 1024,
      // 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
      tools: array_map(fn (Tool $tool) => $tool->withStrict(true), $tools),
      toolChoice: ToolChoiceAuto::with(),
      messages: [
          [
              'role' => 'user',
              'content' => "What's the weather in Paris? Use the get_weather tool.",
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    # 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
    tools: tools.map { |tool| tool.merge(strict: true) },
    tool_choice: Anthropic::ToolChoiceAuto.new,
    messages: [
      { role: "user", content: "What's the weather in Paris? Use the get_weather tool." }
    ]
  )
  ```
</CodeGroup>

此範例將清單中的每個工具都標記為嚴格。一個請求最多可有 20 個嚴格工具，且 MCP、電腦使用與瀏覽器使用工具集項目不接受 `strict`。在較長的工具清單中，請只標記需要的工具。

### 思考區塊與模型及對話綁定

Claude Sonnet 5.5 可讀取來自 Claude Sonnet 5、Claude Opus 4.8、Claude Haiku 4.5 及更早模型的思考區塊，在 Claude API 與 Google Cloud 上也可讀取來自 Claude Haiku 5.5 的思考區塊。它無法讀取來自 Claude Opus 5、Claude Opus 5.5 或任何 Claude Fable 或 Claude Mythos 模型的區塊。API 會捨棄模型無法讀取的區塊。請求仍會傳回 200，且被捨棄的區塊不會計費。請參閱[在對話中途切換模型](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#switching-models)。

每個 Claude Sonnet 5.5 思考區塊也會針對其之前的對話進行簽署。對於在 2026 年 8 月 31 日 00:00 UTC 當天或之後建立的帳戶，API 預設會在 Claude API、Amazon Bedrock 與 Google Cloud 上強制執行此規則。在這些帳戶上，於編輯較早歷史記錄後重播區塊的請求會傳回 400 錯誤。請保持對話為僅附加，並使用[對話中途系統訊息](https://platform.claude.com/docs/zh-TW/build-with-claude/mid-conversation-system-messages)變更指示或工具。Claude Sonnet 5.5 產生的思考區塊只能在產生它們的帳戶或與其連結的帳戶中使用。請參閱[保留思考](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#account-bound-thinking)。

### 在 Claude API 和 Google Cloud 上，電腦使用需要工具集

在 Claude API 和 Google Cloud 上，Claude Sonnet 5.5 僅透過 `computer_toolset_20260801` 工具集支援電腦使用。在這些平台上，`computer_20251124` 會傳回 400 錯誤。Claude Sonnet 5.5 在任何平台上都不接受 `computer_20250124`。請找出您目前傳送的版本：

| 您目前傳送的版本            | 會傳送此版本的起始模型                                        | 在 Claude API 和 Google Cloud 上傳送 | 在 Amazon Bedrock 上傳送 |
| ------------------- | -------------------------------------------------- | ------------------------------- | -------------------- |
| `computer_20251124` | Claude Sonnet 5、Claude Sonnet 4.6                  | `computer_toolset_20260801`     | `computer_20251124`  |
| `computer_20250124` | Claude Sonnet 4.5、Claude Haiku 4.5、Claude Sonnet 4 | `computer_toolset_20260801`     | `computer_20251124`  |

若您會傳送 `fine-grained-tool-streaming-2025-05-14` beta 標頭，請在移至工具集時將其移除。與工具集項目一同傳送時，它會傳回 400 錯誤。請改為在每個需要的工具上設定 `eager_input_streaming: true`。

已傳送工具集的程式碼無需變更。[從 `computer_20251124` 遷移](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)列出了請求與代理迴圈的變更。其他平台請參閱[相容性](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#compatibility)。

### 顧問工具接受的顧問較少

使用[顧問工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/advisor-tool)時，Claude Sonnet 5.5 執行者需要下列其中一個顧問：Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5、Claude Fable 5.1、Claude Mythos 5 或 Claude Mythos 5.1。Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5、Claude Sonnet 4.6 與 Claude Haiku 5.5 顧問會傳回 400 錯誤。建議會以 `advisor_redacted_result` 區塊加密傳回，因此其文字在回應中無法讀取。請參閱[模型相容性](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/advisor-tool#model-compatibility)。

### 工具呼叫之間的文字會在思考區塊中傳回

在 Claude Sonnet 5.5 上，模型在工具呼叫之間撰寫、長度超過一兩句的說明，會以[進度更新 `thinking` 區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#progress-updates)傳回，且在預設 `display` 下為空。較短的評論仍為 `text`。在 Claude Sonnet 5 及更早的模型上，工具呼叫之間的所有文字都會以 `text` 區塊傳回。不會有請求失敗，但顯示這些說明的介面會變得沒有內容。

使用自適應思考時，將 `display` 設為 `"updates"`（beta，`thinking-display-updates-2026-08-18` 標頭）可單獨取得更新，設為 `"summarized"` 則可取得與推理混合的更新。請在每個非空 `thinking` 區塊之後的 `tool_use` 區塊之前呈現該 `thinking` 區塊。使用 [`between_tools`](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking) 時，文字會在不需設定 `display` 的情況下傳回。請參閱[面向使用者的進度更新](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#user-facing-progress-updates)。

### 安全分類器與備援

Claude Sonnet 5.5 會拒絕的類別比 Claude Sonnet 5 更多。拒絕會傳回 `stop_reason: "refusal"`，其 `stop_details` 可能會指出下列其中一個[類別](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#refusal-response)：

* **`"cyber"`：** 該請求可能促成網路危害，例如惡意軟體或漏洞利用程式開發。
* **`"bio"`：** 該請求可能促成生物危害，例如危險的實驗室方法。
* **`"frontier_llm"`：** 該請求可能協助開發競爭的 AI 模型。
* **`"reasoning_extraction"`：** 該請求要求模型在回應文字中重現其內部推理。
* **`"general_harms"`：** 該請求屬於其他使用政策領域。良性工作也可能觸發此類別。

[伺服器端備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#server-side-fallback)（`fallbacks: "default"`，beta，僅限 Claude API）會在 Claude Sonnet 5 上重試 `"cyber"` 和 `"frontier_llm"` 拒絕。它不會重試 `"bio"`、`"reasoning_extraction"` 或 `"general_harms"` 拒絕。請參閱[拒絕與備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback)以及[拒絕如何計費](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#how-refusals-are-billed)。

對於來自 Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 的程式碼而言，即時網路安全防護措施是新增的。若要進行合法的安全工作，請申請[網路安全驗證計畫（Cyber Verification Program）](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet)。

### 其他變更

* **提示快取：** 最小可快取提示為 512 個 token，低於 Claude Sonnet 5、Claude Sonnet 4.6 和 Claude Sonnet 4.5 上的 1,024 個。請參閱[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#cache-limitations)。
* **新功能：** 關於對話中途系統訊息、對話中途工具變更以及逐訊息 effort，請參閱 [Claude Sonnet 5.5 的新功能](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/whats-new-sonnet-5-5#feature-support)。使用 [`between_tools`](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking) 時，effort 無法在對話中途變更。

### 建議變更

重新執行您的 effort 掃描。Claude Sonnet 5.5 有五個 effort 等級：`low`、`medium`、`high`、`xhigh` 和 `max`。Claude API 上的預設值為 `high`。這些等級已重新校準，因此同一等級產生的思考量與 Claude Sonnet 5 上不同。除非您的工作負載屬於代理式或對延遲敏感，否則請從 `high` 開始。對於代理式程式設計和多步驟工具使用，定義明確的任務請從 `medium` 開始，較困難或較長的任務則改用 `high`。對於聊天和其他對延遲敏感的工作，請從 `medium` 或 `low` 開始。請在 `output_config.effort` 中設定等級。請參閱 [Claude Sonnet 5.5 的建議 effort 等級](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#recommended-effort-levels-for-claude-sonnet-5-5)。接著，請對照[提示 Claude Sonnet 5.5](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5) 重新評估模型特定的提示指示。

## 從 Claude Sonnet 4.6 及更早的 Sonnet 模型遷移至 Claude Sonnet 5.5

首先套用前面的所有章節，並替換 `claude-sonnet-4-6`。然後進行以下變更。若使用 Claude Sonnet 4.5 或更早版本，請繼續閱讀後續的子章節。

### 破壞性變更

**原本省略思考的請求會執行思考。** 請參閱[預設會執行思考](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#thinking-on-by-default)和[關閉前置思考](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking)。

**思考預算會傳回錯誤。** Claude Sonnet 4.6 接受 `thinking: {"type": "enabled", "budget_tokens": N}` 作為已棄用的設定。Claude Sonnet 4.5 和 Claude Haiku 4.5 的所有思考都使用此設定。Claude Sonnet 5.5 會傳回 400 錯誤：

```text wrap
"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
```

請移除預算並設定 [effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 等級。預算與 effort 等級之間沒有固定的對應關係，因此請在兩到三個等級下執行您的評估。

之前（Claude Sonnet 4.6）：

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 16000,
      "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
      },
      "messages": [
        {
          "role": "user",
          "content": "..."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-4-6
  max_tokens: 16000
  thinking:
    type: enabled
    budget_tokens: 10000
  messages:
    - role: user
      content: "..."
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=16000,
      thinking={"type": "enabled", "budget_tokens": 10000},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 16000,
    thinking: { type: "enabled", budget_tokens: 10000 },
    messages: [{ role: "user", content: "..." }]
  });
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet4_6,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
      Messages = [new() { Role = Role.User, Content = "..." }]
  };

  var response = await client.Messages.Create(parameters);
  Console.WriteLine(response);
  ```

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

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet4_6,
  	MaxTokens: 16000,
  	Thinking:  anthropic.ThinkingConfigParamOfEnabled(10000),
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_4_6)
      .maxTokens(16000L)
      .enabledThinking(10000L)
      .addUserMessage("...")
      .build();

  Message response = client.messages().create(params);
  IO.println(response);
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 16000,
      messages: [['role' => 'user', 'content' => '...']],
      model: 'claude-sonnet-4-6',
      thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
  );
  ```

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

  message = client.messages.create(
    model: "claude-sonnet-4-6",
    max_tokens: 16000,
    thinking: {
      type: "enabled",
      budget_tokens: 10000
    },
    messages: [
      { role: "user", content: "..." }
    ]
  )
  ```
</CodeGroup>

之後（Claude Sonnet 5.5）：

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 16000,
      "thinking": {
        "type": "adaptive"
      },
      "output_config": {
        "effort": "high"
      },
      "messages": [
        {
          "role": "user",
          "content": "..."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-5-5
  max_tokens: 16000
  thinking:
    type: adaptive
  output_config:
    effort: high
  messages:
    - role: user
      content: "..."
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=16000,
      thinking={"type": "adaptive"},
      output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 16000,
    thinking: { type: "adaptive" },
    output_config: { effort: "high" }, // or "max", "xhigh", "medium", "low"
    messages: [{ role: "user", content: "..." }]
  });
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Messages;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigAdaptive(),
      OutputConfig = new OutputConfig { Effort = Effort.High }, // or Max, Xhigh, Medium, Low
      Messages = [new() { Role = Role.User, Content = "..." }]
  };

  var response = await client.Messages.Create(parameters);
  Console.WriteLine(response);
  ```

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

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 16000,
  	Thinking: anthropic.ThinkingConfigParamUnion{
  		OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortHigh, // or Max, Xhigh, Medium, Low
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5_5)
      .maxTokens(16000L)
      .thinking(ThinkingConfigAdaptive.builder().build())
      .outputConfig(OutputConfig.builder()
          .effort(OutputConfig.Effort.HIGH) // or MAX, XHIGH, MEDIUM, LOW
          .build())
      .addUserMessage("...")
      .build();

  Message response = client.messages().create(params);
  IO.println(response);
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 16000,
      messages: [['role' => 'user', 'content' => '...']],
      model: 'claude-sonnet-5-5',
      thinking: ['type' => 'adaptive'],
      outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low'
  );
  ```

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

  message = client.messages.create(
    model: "claude-sonnet-5-5",
    max_tokens: 16000,
    thinking: {
      type: "adaptive"
    },
    output_config: {
      effort: "high" # or "max", "xhigh", "medium", "low"
    },
    messages: [
      { role: "user", content: "..." }
    ]
  )
  ```
</CodeGroup>

**取樣參數會傳回錯誤。** Claude Sonnet 4.6 及更早的模型以及 Claude Haiku 4.5 接受 `temperature`、`top_p` 和 `top_k`。在 Claude Sonnet 5.5 上，非預設值會傳回 400 錯誤。請將其移除。

**思考文字預設會被省略。** 請參閱[在回應中處理思考](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#thinking-in-responses)。

### 其他變更

* **token 約增加 30%：** Claude Sonnet 5.5 使用 Claude Sonnet 5 的「tokenizer」（分詞器）。與 Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 相比，相同文字產生的 token 約多 30%，實際數量視內容而定。請使用 [token 計數](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)重新計算，並重新檢視 `max_tokens` 和成本。
* **Effort：** `xhigh` 為新增等級，且各等級已重新校準。請參閱[建議變更](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#recommended-changes)。
* **圖片：** Claude Sonnet 5.5 使用高解析度圖片層級，長邊最多 2576 像素，每張圖片最多 4,784 個視覺 token。Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 的上限為 1568 像素和 1,568 個 token。一張 2000×1500 的圖片在 Claude Sonnet 5.5 上耗用的 token 約為 2.5 倍。請參閱[解析度與 token 成本](https://platform.claude.com/docs/zh-TW/build-with-claude/vision#evaluate-image-size)。

### 從 Claude Sonnet 4.5 或更早版本遷移

若使用 Claude Sonnet 4.5、Claude Sonnet 4 或 Claude 3.7 Sonnet，請先套用前面的每個章節，然後進行以下變更。

**預填會傳回錯誤。** Claude Sonnet 5.5 會以 400 錯誤拒絕預填的最後一個助理回合，與 Claude Sonnet 4.6 及 Claude Sonnet 5 相同。Claude Sonnet 4.5、Claude Haiku 4.5 及更舊的模型則接受預填。錯誤內容如下：

```text wrap
This model does not support assistant message prefill. The conversation must end with a user message.
```

請依每個預填的用途進行替換：

* **輸出格式：** 使用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)，或在分類時使用帶有列舉欄位的工具。在 Amazon Bedrock 上，Claude Sonnet 5.5 無法使用結構化輸出。在該平台上，請在提示中描述格式或使用不含 `strict` 的工具，並在您的程式碼中驗證輸出。
* **開場白：** 在系統提示中要求直接回答。
* **不必要的拒絕：** 在使用者訊息中提供清楚的指示通常就已足夠。
* **接續：** 將其移至使用者訊息，例如「Your previous response was interrupted and ended with `[previous_response]`. Continue from where you left off.」
* **上下文提醒：** 將其放在使用者回合中。

**工具輸入跳脫。** 工具呼叫引數中的跳脫方式可能不同。請使用標準 JSON 剖析器剖析 `input`。

**電腦使用。** Claude Sonnet 5.5 不接受 `computer_20250124`。請參閱[電腦使用表格](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#computer-use-toolset)。

**Effort。** Claude Sonnet 4.5 沒有 effort 參數。請依[建議變更](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#recommended-changes)所述，明確設定 effort 等級。

**上下文與輸出。** Claude Sonnet 5.5 具有更大的上下文視窗（無需 beta 標頭）以及更高的輸出上限。請參閱[模型頁面](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/overview)。請移除任何上下文視窗 beta 標頭。

**Beta 標頭。** 移除 `interleaved-thinking-2025-05-14`，因為自適應思考會自動交錯進行。將 `fine-grained-tool-streaming-2025-05-14` 替換為在每個需要的工具上設定 `eager_input_streaming: true`。該標頭與電腦使用或瀏覽器使用工具集項目一同使用時會傳回 400 錯誤。請參閱[細粒度工具串流](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/fine-grained-tool-streaming)。

**結構化輸出。** `output_format` 參數已棄用，並將於未來移除。若仍要使用，請加入 `structured-outputs-2025-11-13` beta 標頭。若未加入，API 會傳回 400 錯誤。請改用 `output_config.format`。

### 從 Claude Sonnet 4 或更早版本遷移

Claude Sonnet 4 已在 Claude API 上停用，但仍可在 Amazon Bedrock 和 Google Cloud 上使用。Claude 3.7 Sonnet 已停用。從這兩個模型中的任一個遷移時，請先套用前面的所有章節，再進行以下變更：

* **工具版本：** 使用 `text_editor_20250728`，工具名稱為 `str_replace_based_edit_tool`，且沒有 `undo_edit` 命令。使用 `code_execution_20260521`。請參閱[文字編輯器工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/text-editor-tool)和[程式碼執行工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version)。
* **停止原因：** 處理 `refusal`。Claude 4.5 及更新的模型在達到上下文視窗限制時也會以 `model_context_window_exceeded` 停止。請參閱[處理停止原因](https://platform.claude.com/docs/zh-TW/build-with-claude/handling-stop-reasons)。
* **結尾換行字元：** Claude 4.5 及更新的模型會在工具呼叫字串參數中保留結尾換行字元。
* **舊版 beta 標頭：** 移除 `token-efficient-tools-2025-02-19` 和 `output-128k-2025-02-19`。
* **提示：** 對照[提示撰寫最佳實務](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/claude-prompting-best-practices)檢閱您的提示。

## 從 Claude Haiku 4.5 遷移至 Claude Sonnet 5.5

首先套用直到並包括[從 Claude Sonnet 4.5 或更早版本遷移](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45)的所有章節，但略過 Claude Sonnet 4 子章節。然後進行以下變更：

* **模型 ID：** 將 `claude-haiku-4-5-20251001` 或別名 `claude-haiku-4-5` 替換為 `claude-sonnet-5-5`。
* **成本：** 每 token 價格較高，且相同文字會產生更多 token。請重新計算 token 並重新建立成本基準。請參閱 [Claude 定價](https://platform.claude.com/docs/zh-TW/about-claude/pricing)。
* **提示快取：** 最小可快取提示從 4,096 個 token 降至 [Claude Sonnet 5.5 的最小值](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#other-changes-from-claude-sonnet-5)。
* **交錯思考：** 自適應思考會自動在工具呼叫之間執行，無需 beta 標頭。
* **路由：** Claude Sonnet 5.5 可讀取 Claude Haiku 4.5 的思考區塊。向上移轉的對話會保留其推理。移回 Claude Haiku 4.5 的對話則會捨棄 Claude Sonnet 5.5 的區塊。