ai-docs

Migrating to Claude Sonnet 5.5

Properties1
tagsmodels, migration, sonnet-5-5, thinking, tool-use, api

原典: Migrating to Claude Sonnet 5.5 ／ 日本語版

一行要約

Sonnet 5.5 では 5つの設定が 400 を返す（thinking budget、サンプリングパラメータ、assistant の prefill、強制ツール使用、thinking: {"type": "disabled"}）。thinking は既定でオン、thinking ブロックは会話とアカウントに結びつくので会話は追記だけに保ち、effort は sweep をやり直す。

要点

まず効く2つ

thinking は既定でオン:

モデルthinking 無しで受け付ける thinking.type既定の display
Sonnet 5.5On"adaptive", "between_tools""omitted"
Sonnet 5On"adaptive", "disabled""omitted"
Sonnet 4.6Off"adaptive", "disabled", "enabled"（非推奨）"summarized"
Sonnet 4.5 と Haiku 4.5Off"disabled", "enabled""summarized"

thinking なしで動いていたコードに要る3つ —— content ブロックを type で読む（content[0].text は壊れる）、thinking ブロックを空のものも含めてそのまま返す、max_tokens を見直す（thinking と text の両方を含み、thinking は出力として課金される）。

事前の thinking を切るのは between_tools（disabled は 400）。どのプラットフォームでも beta ヘッダ無しで使え、low / medium / high でだけ受け付ける。display / budget_tokens / block_binding を一緒に送ると 400。サーバ側フォールバックで Sonnet 5 に落ちたリクエストは、そちらで disabled として走る。 between_tools では会話途中で effort を変えられない。

Sonnet 5 からの破壊的変更（全員が対象）

  • モデル ID は claude-sonnet-5-5（日付の接尾辞なし）
  • 強制ツール使用（tool_choice の any / tool）は 400（token counting のエンドポイントでも）。auto にしてツールを strict: true、いつ使うかを prompt に書く。1リクエストで strict は最大20個、MCP・computer use・browser use の toolset には付けられない。Amazon Bedrock では structured outputs（strict を含む）が Sonnet 5.5 で使えないので、strict 無しの auto にして入力を検証する
  • thinking ブロックはモデルと会話に結びつく

Each Claude Sonnet 5.5 thinking block is also signed over the conversation before it. For accounts created on or after a set date, the API enforces this by default, on the Claude API, Amazon Bedrock, and Google Cloud. On those accounts, a request that replays a block after an edit to earlier history returns a 400 error. Keep conversations append-only, and change instructions or tools with mid-conversation system messages.

Claude Sonnet 5.5 の各 thinking ブロックは、その前の会話に対して署名されている。一定の日以降に作られたアカウントでは、Claude API・Amazon Bedrock・Google Cloud で既定でこれが強制される。そのアカウントでは、前の履歴を編集した後にブロックを送り返すリクエストは 400 になる。 会話は追記だけに保ち、指示やツールの変更は会話途中の system message で行え。

Sonnet 5.5 が読めるのは Sonnet 5 / Opus 4.8 / Haiku 4.5 以前のブロックで、Opus 5 / Opus 5.5 / Fable / Mythos のブロックは読めない（API が落とし、200 のまま課金もされない）。ブロックは生んだアカウントか、それに結びついたアカウントでしか使えない。

  • computer use は Claude API と Google Cloud では computer_toolset_20260801 だけ（computer_20251124 は 400）。computer_20250124 はどこでも受け付けない。Bedrock では computer_20251124。toolset と一緒の fine-grained-tool-streaming-2025-05-14 ヘッダは 400 なので、ツールごとの eager_input_streaming: true にする
  • advisor tool の相手が絞られた —— Opus 5 / Opus 5.5 / Sonnet 5.5 / Fable 5 / Fable 5.1 / Mythos 5 / Mythos 5.1 だけ（Opus 4.8 / 4.7 / 4.6 / Sonnet 5 / 4.6 は 400）。助言は advisor_redacted_result として暗号化されて返り、本文は読めない
  • ツール呼び出しの合間の文が thinking ブロックで返る —— 1〜2文より長いノートは進捗更新の thinking ブロック（既定の display では空）、短いものは text。失敗するリクエストは無いが、それを表示する画面が黙る。adaptive では display: "updates"（beta）か "summarized"、各非空の thinking ブロックをその後の tool_use の前に描く
  • 安全分類器の拒否カテゴリが Sonnet 5 より多い —— cyber / bio / frontier_llm / reasoning_extraction / general_harms。サーバ側フォールバック（fallbacks: "default"、beta、Claude API のみ）は cyber と frontier_llm だけを Sonnet 5 で再試行する
  • prompt cache の最小は 512 トークン（Sonnet 5 / 4.6 / 4.5 の 1,024 から下がった）
  • effort の sweep をやり直す —— 5段階、Claude API の既定は high、レベルは較正し直されている

Sonnet 4.6 以前から

  • thinking budget（"enabled" + budget_tokens）は 400 —— effort にする。budget から effort への決まった対応は無いので、2〜3レベルで eval を回す
  • temperature / top_p / top_k の既定以外の値は 400 —— 消す
  • 同じ文で約30% トークンが増える（Sonnet 5 のトークナイザ。Sonnet 4.6 / 4.5 / Haiku 4.5 比）
  • 画像は高解像度の段（長辺 2576px・最大 4,784 トークン。旧モデルは 1568px・1,568 トークン）。2000×1500 の画像は約2.5倍のトークン

Sonnet 4.5 以前から

  • prefill は 400 —— 目的で置き換える（出力形式 → structured outputs や enum のツール、前置き → system prompt で直接の答えを頼む、不要な拒否 → user メッセージの明確な指示、続き → user メッセージに移す、context のリマインダ → user ターンへ）
  • ツールの入力は標準の JSON パーサで読む（エスケープが違いうる）
  • effort を明示する、context window の beta ヘッダを消す、interleaved-thinking-2025-05-14 を消す、output_format は output_config.format に

Haiku 4.5 から

トークン単価が上がり、同じ文のトークンも増えるので、数え直してコストの基準を引き直す。Sonnet 5.5 は Haiku 4.5 の thinking ブロックを読める —— 上げる切り替えは推論を保ち、Haiku 4.5 へ戻すと Sonnet 5.5 のブロックは落ちる。

移行を自動化する

Automate your migration with the Claude API skill. In Claude Code, run /claude-api migrate to invoke the bundled Claude API skill.

Claude API skill で移行を自動化せよ。 Claude Code で /claude-api migrate を走らせると、同梱の Claude API skill が呼ばれる。

モデル ID の置き換え、破壊的なパラメータ変更、prefill の置き換え、effort の較正を適用し、手で確かめる項目のチェックリストを出す。ファイルを編集する前に範囲（作業ディレクトリ全体・サブディレクトリ・ファイル一覧）の確認を求める。 Claude Managed Agents を使っているなら、モデル名の変更以外は要らない。

そのまま使える具体例

移行チェックリスト（すべての出発点で）:

  • モデル ID を claude-sonnet-5-5 に
  • content ブロックを type で読み、thinking ブロックをそのまま返す
  • 事前の thinking を切り続けるなら between_tools を high 以下で
  • 強制ツール使用を auto + strict に（Bedrock では auto だけ）
  • 会話を追記だけに保つ
  • Claude API と Google Cloud では computer use を toolset に（fine-grained-tool-streaming-2025-05-14 を外す）
  • advisor を対応する相手に、助言が暗号化されることを前提に
  • ツール呼び出しの合間の文を thinking ブロックから読む
  • 拒否を扱い、フォールバックを設定する
  • effort の sweep をやり直し、コストの基準を引き直す
/claude-api migrate

原典で言及されている関連文書

バックリンク