---
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>

讓 Claude Code 為您遷移程式碼

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

Claude Sonnet 5.5 的價格與 Claude Sonnet 5 相同，唯獨提示快取讀取的費用為每百萬個 token 0.10 美元，是 Claude Sonnet 5 費率的一半。請參閱[定價](https://platform.claude.com/docs/zh-TW/about-claude/pricing)。關於其「context window」（上下文視窗）與輸出限制，請參閱 [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」（投入程度）等級，並省略了五項會傳回 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: 2026-10-21" \
    -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.type === "text");
  console.log(textBlock?.text);
  ```

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

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 4096,
      Messages = [
          new UserMessageParam
          {
              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: Model::CLAUDE_SONNET_5_5,
      outputConfig: ['effort' => 'medium'],
  );

  echo "Stop reason: {$message->stopReason}", PHP_EOL;
  foreach ($message->content as $block) {
      if ($block instanceof \Anthropic\Messages\TextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

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

  message = client.messages.create(
    model: Anthropic::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.is_a?(Anthropic::Models::TextBlock)
  end
  ```
</CodeGroup>

## 思考預設會執行

在 Claude Sonnet 5.5 上，沒有 `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 的平台上使用。它在 `low`、`medium` 與 `high` 投入程度下皆可接受。在 `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` 時，投入程度無法在對話中途變更：若每則訊息的 `output_config.effort` 與目前生效的等級不同，會傳回 400 錯誤。若要在每個回合中變更投入程度，請使用自適應思考。關於提示撰寫指引，請參閱[在不進行前置思考的情況下執行](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: 2026-10-21" \
    -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 UserMessageParam { 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: 2026-10-21" \
    -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 UserMessageParam { 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` 或更低的投入程度下傳送[最低的思考設定](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 tools）。
* 保持對話為[僅附加（append-only）](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#thinking-blocks)。
* 將電腦使用移至[工具集（toolset）](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#computer-use-toolset)，且不使用 `fine-grained-tool-streaming-2025-05-14` beta 標頭。在 Amazon Bedrock 上，`computer_20251124` 也可運作。
* [將顧問工具](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#advisor-tool)與支援的顧問搭配使用，並預期會收到加密的建議。
* 從 `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)，並設定備援（fallback）。
* [重新執行您的投入程度測試](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`。
* 以投入程度等級取代[思考預算](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 或更早版本

* 替換[助理預填（assistant prefill）](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45)。
* 使用標準 JSON 剖析器剖析工具呼叫輸入。
* 明確設定 `output_config.effort`。
* 移除任何上下文視窗 beta 標頭。
* 移除 `interleaved-thinking-2025-05-14`，並將 `fine-grained-tool-streaming-2025-05-14` 替換為 `eager_input_streaming`。
* 將 `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)。

之前（Claude Sonnet 5）：

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 is 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 UserMessageParam { 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: 2026-10-21" \
    -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 is 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,
      # strict tool use（嚴格工具使用）：每次呼叫皆符合工具的 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 UserMessageParam
          {
              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 及[更早模型](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#earlier-models)的思考區塊。在 Claude API 與 Claude Models on Google Cloud (Google managed) 上，它也可讀取來自 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)。

請保持對話為僅附加，讓思考區塊能通過[前綴檢查](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking/prefix-checks#prefix-check)。若要變更指示或工具，請參閱[對話中途的系統訊息與工具變更](https://platform.claude.com/docs/zh-TW/build-with-claude/mid-conversation-system-messages)。

未通過[前綴檢查](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking/prefix-checks#prefix-check)可能會、也可能不會導致 [400 錯誤](https://platform.claude.com/docs/zh-TW/api/errors#thinking-block-conversation-mismatch)。若要識別並處理這兩種情況，請參閱[思考區塊的前綴檢查](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking/prefix-checks)。

前綴檢查會在 Claude API 及[部分雲端平台](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#feature-availability)上執行。

Claude Sonnet 5.5 的思考區塊僅能在產生它們的帳戶或與其連結的帳戶中使用。請參閱[保留思考](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#account-bound-thinking)。

### 部分電腦使用工具版本不受支援

Claude Sonnet 5.5 透過 `computer_toolset_20260801` 工具集支援電腦使用。在 Amazon Bedrock 上，Claude Sonnet 5.5 也接受搭配 `computer-use-2025-11-24` beta 標頭的 `computer_20251124` 工具。對於任何不接受的電腦使用工具版本（例如 Claude API 上的 `computer_20251124`），Claude Sonnet 5.5 會傳回 400 錯誤。它在任何平台上都不接受 `computer_20250124`。

已使用工具集的整合無需任何變更。若要移至工具集，請將 `computer_20251124` 或 `computer_20250124` 替換為 `computer_toolset_20260801`，並移除該版本的 beta 標頭。關於請求與代理迴圈（agent loop）的變更，請參閱[從 `computer_20251124` 遷移](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)。

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

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

使用[顧問工具](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 Fable 5.2、Claude Mythos 5、Claude Mythos 5.1 或 Claude Mythos 5.2。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` 區塊之前呈現該區塊。使用 [`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"`）在 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) 上為 beta 版，會在 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)。
* **新功能：** 關於對話中途的系統訊息、對話中途的工具變更以及每則訊息的投入程度，請參閱 [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) 時，投入程度無法在對話中途變更。

### 建議變更

重新進行投入程度測試。Claude Sonnet 5.5 有五個投入程度等級：`low`、`medium`、`high`、`xhigh` 與 `max`。Claude API 上的預設值為 `high`。這些等級已重新校準，因此同一等級產生的思考量與 Claude Sonnet 5 上不同。除非您的工作負載屬於代理型或對延遲敏感，否則請從 `high` 開始。對於代理式程式開發與多步驟工具使用，規格明確的任務請從 `medium` 開始，較困難或較長的任務則改用 `high`。對於聊天及其他對延遲敏感的工作，請從 `medium` 或 `low` 開始。請在 `output_config.effort` 中設定等級。請參閱 [Claude Sonnet 5.5 的建議投入程度等級](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.
```

請移除預算並設定[投入程度](https://platform.claude.com/docs/zh-TW/build-with-claude/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: 2026-10-21" \
    -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 UserMessageParam { 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: Model::CLAUDE_SONNET_4_6,
      thinking: ['type' => 'enabled', 'budgetTokens' => 10000],
  );
  ```

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

  message = client.messages.create(
    model: Anthropic::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: 2026-10-21" \
    -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 UserMessageParam { 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: 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: Anthropic::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>

**取樣參數會傳回錯誤。** 請移除 `temperature`、`top_p` 和 `top_k`。

**思考文字預設會被省略。** 請參閱[處理回應中的思考](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，相同的文字會產生約多 30% 的 token，視內容而定。請使用 [token 計數](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)重新計算，並重新檢視 `max_tokens` 與成本。
* **投入程度：** Claude Sonnet 5.5 支援 `xhigh`，且各等級已重新校準。請參閱[建議變更](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#recommended-changes)。
* **圖片：** Claude Sonnet 5.5 使用高解析度圖片層級，長邊最多 2,576 像素，每張圖片最多 4,784 個視覺 token。Claude Sonnet 4.6、Claude Sonnet 4.5 與 Claude Haiku 4.5 的上限為 1,568 像素與 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)，或在分類時使用帶有列舉欄位的工具。
* **開場白：** 在系統提示中要求直接回答。
* **不必要的拒絕：** 在使用者訊息中提供清楚的指示通常就已足夠。
* **接續：** 將其移至使用者訊息，例如「您先前的回應被中斷，結尾為 `[previous_response]`。請從中斷處繼續。」
* **上下文提醒：** 將其放在使用者回合中。

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

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

**投入程度。** Claude Sonnet 4.5 沒有投入程度參數。請明確設定投入程度等級（請參閱[建議變更](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#recommended-changes)）。

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

**Beta 標頭。** 請移除 `interleaved-thinking-2025-05-14`，因為自適應思考會自動交錯進行。請以在每個需要的工具上設定 `eager_input_streaming: true` 取代 `fine-grained-tool-streaming-2025-05-14`。該標頭與電腦使用或瀏覽器使用工具集項目一同傳送時會傳回 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 上停用，但可在 Claude Models on Google Cloud (Google managed) 與 Amazon Bedrock 上使用。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 並重新建立成本基準。請參閱[定價](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)。
* **交錯思考：** 自適應思考會自動在工具呼叫之間執行。
* **路由：** Claude Sonnet 5.5 可讀取 Claude Haiku 4.5 的思考區塊。向上移轉的對話會保留其推理。移回 Claude Haiku 4.5 的對話則會捨棄 Claude Sonnet 5.5 的區塊。