Claude Haiku 5.5移行ガイド

このガイドでは、Claude Haiku 4.5 を呼び出すコードを 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. Claude API または Google Cloud でコンピュータ使用を利用している場合は、computer_20250124 から computer_toolset_20260801 ツールセットに移行します。コンピュータ使用をツールセットに移行するを参照してください。
8. 保存した会話を別のアカウントを通じて再送信している場合は、各会話をそれを生成したアカウントを通じて再送信します。思考ブロックはそれを生成したアカウントを通じて再送信するを参照してください。
9. 会話内のリクエスト間で system、tools、または以前の messages を変更し、かつ思考ブロックを送り返している場合は、会話を追記のみ（append-only）に保ちます。以前のターンを変更しないを参照してください。
10. stop_reason: "refusal" を処理します。Claude Haiku 5.5 はリクエストを拒否する可能性のある安全性分類器を実行し、サーバーサイドフォールバックはありません。セーフガードによる拒否を参照してください。

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

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

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

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

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 フィールドを持つツールを使用します。構造化出力をサポートしていない Claude in Amazon Bedrock では、ツールを使用してください。
• 前置き： システムプロンプトで直接的な回答を求めます。
• 続きの生成： ユーザーメッセージに移します。例：「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 エラーを返します。

統合を移行するには、computer-use-2025-01-24 ベータヘッダーを削除し、tools のエントリを {"type": "computer_toolset_20260801"} に置き換えます。その後、computer_20251124 から移行するに記載されているその他のリクエストおよびエージェントループの変更を行います。具体的には、input.action ではなく各メンバーの tool_use ブロックの name と toolset_name に基づいて処理を振り分け、1つのターン内のそのようなブロックをすべて処理し、結果に 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 を設定したリクエストでのみ発生します。エラーを引き起こす変更と、その代わりに行うべきことについては、変更が必要なのは誰かを参照してください。