Claude Haiku 5.5移行ガイド

このガイドでは、Claude Haiku 4.5を呼び出すコードをClaude Haiku 5.5に移行する方法を説明します。Claude Haiku 3.5またはClaude Haiku 3を呼び出すコードの場合は、Claude Haiku 3.5以前のHaikuモデルからClaude Haiku 5.5への移行の変更も行ってください。代わりにSonnetまたはOpusモデルにアップグレードする場合は、モデルバージョン間のアップグレードを参照してください。Claude Haiku 4.5が利用可能な期間については、モデルの非推奨化を参照してください。

移行元モデル別の移行チェックリスト

グループを上から順に進め、現在のモデルが記載されているグループで終了してください。Claude Haiku 4.5を使用している場合は、最初のグループがリスト全体になります。各項目は、コードで行う1つの変更です。

すべての移行元モデル

1. モデル ID を、ご利用のプラットフォーム向けの Claude Haiku 5.5 の ID に置き換えます。Claude Haiku 5.5 のモデル ID を使用するを参照してください。
2. 同じテキストでもより多くのトークンとしてカウントされ、大きな画像はより多くのビジュアルトークンとしてカウントされるため、プロンプトのトークン数を再計測し、max_tokens の上限とコスト見積もりを見直します。トークン数を再計測するを参照してください。
3. リクエストで thinking: {"type": "enabled", "budget_tokens": N} を送信している場合は、thinking を {"type": "adaptive"} に変更します。思考を設定するを参照してください。
4. コードが最初のコンテンツブロックを回答として読み取っている場合は、代わりに type でブロックを選択します。思考を設定するを参照してください。
5. リクエストから temperature、top_p、top_k を削除します。サンプリングパラメータを削除するを参照してください。
6. モデルに続きを生成させるために messages をアシスタントターンで終えている場合は、代わりにユーザーターンで終えるようにします。アシスタントのプリフィルを置き換えるを参照してください。
7. コンピュータ使用を利用している場合は、computer_20250124 を置き換えます。Claude API と Google Cloud では computer_toolset_20260801 ツールセットに、Amazon Bedrock では computer_20251124 と computer-use-2025-11-24 ベータヘッダーに置き換えます。コンピュータ使用をツールセットに移行するを参照してください。
8. 保存した会話を別のアカウントを通じて再送信している場合は、各会話をそれを生成したアカウントを通じて再送信します。思考ブロックはそれを生成したアカウントを通じて再送信するを参照してください。
9. 会話内のリクエスト間で system、tools、または以前の messages を変更し、かつ思考ブロックを送り返している場合は、会話を追記のみ（append-only）に保ちます。以前のターンを変更しないを参照してください。
10. stop_reason: "refusal" を処理します。Claude Haiku 5.5 はリクエストを拒否する可能性のある安全性分類器を実行し、サーバーサイドフォールバックはありません。セーフガードによる拒否を参照してください。
11. Amazon Bedrock で構造化出力（output_config.format または strict: true ツール）を使用している場合は、プロンプトで形式を説明するか strict なしのツールを使用し、コード内で出力を検証します。Amazon Bedrock では Claude Haiku 5.5 の構造化出力は利用できません。

組織が Claude Haiku 4.5 で Priority Tier のコミットメントを持っている場合は、キャパシティを別途計画してください。Priority Tier は Claude Haiku 5.5 ではサポートされていません。

Claude Haiku 3.5以前

1. Claude Haiku 3.5またはClaude Haiku 3のモデルIDを、ご利用のプラットフォーム向けのClaude Haiku 5.5のIDに置き換えます。Claude Haiku 3.5以前のHaikuモデルからClaude Haiku 5.5への移行を参照してください。
2. レガシーのcode_execution_20250522ツールを使用している場合は、code_execution_20250825以降に移行します。
3. テキストエディタツールを使用している場合は、text_editor_20250728に移行します。
4. refusalおよびmodel_context_window_exceededの停止理由を処理します。
5. コードがツール呼び出しの文字列パラメータを完全一致で照合している場合は、末尾の改行を許容するようにします。
6. プロンプトを見直します。

Claude Haiku 5.5 のモデル ID を使用する

Claude Haiku 4.5 のモデル ID を、ご利用のプラットフォーム向けの Claude Haiku 5.5 の ID に置き換えます。

claude-haiku-5-5 は日付サフィックスのない固定のモデル ID であり、別途エイリアスはありません。

トークン数を再計測する

Claude Haiku 5.5 は、Claude 4.7 以降のモデルと同じ新しい「tokenizer」（トークナイザー）を使用します。このトークナイザーを使用するすべてのモデルと同様に、同じ入力テキストでも Claude Haiku 5.5 では Claude Haiku 4.5 よりも約30%多くのトークンが生成されます。正確な増加量はコンテンツによって異なります。リクエスト、レスポンス、ストリーミングイベントの形式は変わりません。変わるのは、トークン単位で計測または予算化しているものすべてです。

• 同じテキストに対する usage フィールドとトークンカウントの結果が大きくなります。
• 一定のトークン数に収まるテキストが少なくなります。
• Claude Haiku 4.5 向けに調整した max_tokens の上限では、同等の出力が途中で切れる可能性があります。
• Claude Haiku 4.5 のトークン数から算出したコスト見積もりは、Claude Haiku 5.5 のトークン数と料金（長いプロンプトに対するより高い料金を含む）で再計算する必要があります。ロングコンテキストの料金を参照してください。

大きな画像もより多くのトークンを消費する可能性があります。Claude Haiku 5.5 は高解像度の画像ティアを使用し、長辺が2,576ピクセルまたは4,784ビジュアルトークンを超える画像を縮小します。Claude Haiku 4.5 以前の Haiku モデルは標準ティアを使用し、長辺が1,568ピクセルまたは1,568ビジュアルトークンを超える画像を縮小します。2,000×1,500ピクセルの画像は、Claude Haiku 5.5 では Claude Haiku 4.5 の約2.5倍のビジュアルトークンを消費します。解像度とトークンコストを参照してください。

Claude Haiku 4.5 で計測したトークン数を再利用するのではなく、model を claude-haiku-5-5 に設定してプロンプトのトークン数を計測してください。

思考を設定する

Claude Haiku 5.5 では、思考の設定方法が Claude Haiku 4.5 とは異なります。thinking の値が {"type": "enabled", "budget_tokens": N} の場合は 400 エラーが返されるため、この値を送信しているリクエストには新しい thinking の値が必要です。

変更前は、Claude Haiku 4.5 へのリクエストで thinking をトークン予算付きの enabled に設定していました。

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

変更後は、Claude Haiku 5.5 への同じリクエストで「adaptive thinking」（適応型思考）を使用します。thinking の値が変わり、output_config.effort でモデルがどの程度思考するかを設定します。

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

適応型思考はデフォルトで有効になっているため、リクエストで thinking を設定していなくても、レスポンスが1つ以上の thinking ブロックで始まる場合があります。thinking を未設定のままにするか {"type": "adaptive"} に設定し、「effort」（エフォート）を調整手段として使用してください。Claude Haiku 4.5 を思考なしで実行していた場合や、トークンを節約するために小さな予算で実行していた場合は、より低いエフォートレベルを選択します。低いレベルではモデルの思考量が減り、単純なリクエストでは思考を完全に省略することもあります。プロンプトに関するガイダンスについては、エフォートを使用して思考を制御するを参照してください。コンテンツブロックは位置ではなく type フィールドで選択し、thinking ブロックはツール結果とともに変更せずに送り返してください。

思考トークンは max_tokens にカウントされるため、max_tokens が小さいリクエストでは、thinking ブロックの後、テキストが出力される前に stop_reason: "max_tokens" で停止する可能性があります。Claude Haiku 4.5 向けに小さな max_tokens を設定していた場合は、思考の余地を残すために値を引き上げるか、より低いエフォートレベルを選択してください。

以前のアシスタントターンの思考ブロックはコンテキストに残り、入力トークンとしてカウントされます。Claude Haiku 4.5 では最新のターンの思考ブロックのみが保持されていました。そのため、マルチターンの会話では、トークナイザーの変更だけでは説明できないほど多くの入力トークンが発生します。古いブロックを削除するには、思考ブロックのクリアを使用してください。モデル別の思考ブロックの保持を参照してください。

Claude Haiku 4.5 は要約された思考を返していましたが、Claude Haiku 5.5 はデフォルトで、各 thinking ブロックを空の thinking フィールドと signature のみで返します。要約された思考を受け取るには、thinking: {"type": "adaptive", "display": "summarized"} を設定してください。

Claude Haiku 5.5 は強制的な tool_choice（any または名前付きツール）を受け付けますが、レスポンスはツール呼び出しから始まり、thinking ブロックは含まれません。ツールを呼び出す前にモデルに思考させるには、tool_choice: {"type": "auto"} を使用し、いつツールを使用するかをプロンプトで指示してください。

Claude Haiku 5.5 は、Claude Sonnet 5、Claude Opus 4.8、Claude Haiku 4.5、およびそれ以前のモデルの思考ブロックを読み取るため、Claude Haiku 4.5 から Claude Haiku 5.5 に切り替えた会話でも推論が保持されます。Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5、または Claude Fable や Claude Mythos のいずれのモデルのブロックも読み取りません。API はそれらのブロックをエラーなしで破棄します。Claude API と Google Cloud では、Claude Opus 5.5 と Claude Sonnet 5.5 は Claude Haiku 5.5 のブロックを読み取ります。会話の途中でのモデルの切り替えを参照してください。

サンプリングパラメータを削除する

Claude Haiku 4.5 は temperature、top_p、top_k を受け付けます。Claude Haiku 5.5 では、これら3つすべてを省略し、代わりにプロンプトでモデルの動作を誘導してください。リクエストに temperature を含める場合、その値は 1 でなければなりません。top_p を含める場合、その値はデフォルトの 0.99 でなければなりません。それ以外の temperature または top_p の値は、top_p が 1 の場合も含めて 400 エラーを返します。top_k の値を含めた場合も、temperature と top_p の両方を含めたリクエストも同様です。

アシスタントのプリフィルを置き換える

「prefill」（プリフィル）とは、messages の最後に置かれ、モデルがその続きを生成するアシスタントターンのことです。Claude Haiku 4.5 は思考が無効の場合にプリフィルを受け付けます。Claude Haiku 5.5 は、思考を無効にしていても 400 エラーでこれを拒否します。messages はユーザーターンで終え、各プリフィルをその目的に応じて置き換えてください。

• 出力形式： 構造化出力を使用するか、分類には enum フィールドを持つツールを使用します。Amazon Bedrock では、Claude Haiku 5.5 の構造化出力は利用できません。その場合は、プロンプトで形式を説明するか strict なしのツールを使用し、コード内で出力を検証してください。
• 前置き： システムプロンプトで直接的な回答を求めます。
• 続きの生成： ユーザーメッセージに移します。例：「Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.」
• コンテキストのリマインダー： ユーザーターンに含めます。

コンピュータ使用をツールセットに移行する

Claude Haiku 4.5 は、computer-use-2025-01-24 ベータヘッダーとともに computer_20250124 ツールを通じてコンピュータ使用をサポートしています。Claude API と Google Cloud では、Claude Haiku 5.5 は computer_toolset_20260801 ツールセットを通じてのみコンピュータ使用をサポートし、computer_20250124 を宣言したリクエストは 400 エラーを返します。Amazon Bedrock でも、Claude Haiku 5.5 は computer_20250124 を受け付けません。computer-use-2025-11-24 ベータヘッダーとともに computer_20251124 ツールバージョンを使用してください。

統合をツールセットに移行するには、computer-use-2025-01-24 ベータヘッダーを削除し、tools のエントリを {"type": "computer_toolset_20260801"} に置き換えます。次に、computer_20251124 から移行するに記載されているその他のリクエストおよびエージェントループの変更を行います。input.action ではなく、各メンバーの tool_use ブロックの name と toolset_name に基づいて処理を振り分け、ターン内のそのようなブロックをすべて処理し、結果に toolset_name を含めて返します。ツールセットではズームがデフォルトで有効になっています。環境でズームを実装していない場合は、"configs": {"zoom": {"enabled": false}} を追加してください。fine-grained-tool-streaming-2025-05-14 ベータヘッダーを送信している場合は削除してください。ツールセットのエントリと併用すると 400 エラーを返します。その他のプラットフォームについては、コンピュータ使用ツールの互換性セクションを参照してください。

Claude API と Google Cloud では、Claude Haiku 5.5 はウェブページ内のタスク向けにブラウザ使用ツール（browser_toolset_20260801）もサポートしています。Claude Haiku 4.5 はこれをサポートしていません。

思考ブロックはそれを生成したアカウントを通じて再送信する

Claude Haiku 5.5 の思考ブロックは、それを生成したアカウント、またはそのアカウントにリンクされたアカウントでのみ機能します。別のアカウントがこれらのブロックを送信すると、API はモデルに渡す前にそのブロックを破棄し、リクエストはその推論なしで成功します。これは、会話を保存して別のアカウントを通じて再送信するコード、たとえば1つの会話ストアから複数の顧客にサービスを提供するサービスなどに影響します。各会話は、それを生成したアカウントを通じて再送信してください。思考ブロックはそれを生成したアカウントに留まるを参照してください。

以前のターンを変更しない

Claude Haiku 5.5 の思考ブロックは、それより前に送信されたすべての内容が変更されていない間のみ有効です。system、tools、または以前の messages を変更した後に思考ブロックを送り返すリクエストは、400 エラーを返します。Claude Haiku 4.5 はこのチェックを行いません。会話は追記のみに保ってください。2026年8月31日 00:00 UTC より前に作成されたアカウントでは、このエラーは thinking.block_binding.prefix_mismatch_behavior を設定したリクエストでのみ発生します。エラーを引き起こす変更と、その代わりに行うべきことについては、変更が必要なのは誰かを参照してください。

Claude Haiku 3.5以前のHaikuモデルからClaude Haiku 5.5への移行

Claude Haiku 3.5はClaude APIとAmazon Bedrockで廃止済みであり、Claude Haiku 3はClaude APIとGoogle Cloudで廃止済みです。廃止済みのモデルへのリクエストは失敗します。Google Cloudでは、Claude Haiku 3.5は非推奨として記載されており、既存の顧客のみが利用できます。モデルの非推奨化を参照してください。

いずれのモデルからの移行でも、まず前述のすべてのセクションを適用し、その後に以下の変更を行ってください。

• モデルID： claude-3-5-haiku-20241022、そのエイリアスであるclaude-3-5-haiku-latest、またはclaude-3-haiku-20240307をclaude-haiku-5-5に置き換えます。Google Cloudでは、claude-3-5-haiku@20241022をclaude-haiku-5-5に置き換えます。Amazon Bedrockでは、Claude Haiku 5.5のモデルIDを使用するに記載されているClaude Haiku 5.5のIDを使用します。
• コード実行： Claude Haiku 5.5はcode_execution_20250825以降のバージョンを受け付けます。Pythonのみに対応したレガシーのcode_execution_20250522を使用している場合は、これらのいずれかに移行してください。最新のツールバージョンへのアップグレードを参照してください。
• テキストエディタ： テキストエディタツールを使用している場合は、text_editor_20250728（ツール名str_replace_based_edit_tool）に移行してください。このバージョンにはundo_editコマンドはありません。テキストエディタツールを参照してください。
• 停止理由： refusalとmodel_context_window_exceededを処理します。停止理由の処理を参照してください。
• 末尾の改行： Claude 4.5以降のモデルは、ツール呼び出しの文字列パラメータの末尾の改行を保持します。コードがこれらの文字列を完全一致で照合している場合は、末尾の改行を許容するようにしてください。
• プロンプト： Claude 4以降のモデルは、より簡潔で直接的なコミュニケーションスタイルを持ち、明示的な指示を必要とします。Claude Haiku 5.5へのプロンプトおよびプロンプトのベストプラクティスに照らしてプロンプトを見直してください。