Claude Haiku 5.5へ移行する手順 — 4.5から直す11項目

Claude Haiku 4.5のコードをClaude Haiku 5.5に移すには、モデルIDの差し替えだけでは足りません。thinkingの指定、サンプリング引数、assistantのprefillは、そのまま送ると400エラーになります。トークン数は同じ文章でも約30%増え、max_tokensとコスト試算にも影響します。

この記事では、Messages APIを呼ぶコードを対象に、Haiku 4.5から5.5への移行を11項目のチェックリストとして順に進めます。リクエストを組み立てる側の修正から、会話の保存や拒否応答の扱いまで、直す場所の順に並べました。Managed Agentsを使っている場合は、モデル名の更新以外の変更は要りません。

11項目の全体像と、直す順番

Claude Haiku 4.5からの移行で触る項目は、次の11個です。性質で3つに分けると、着手の順番が決まります。

着手は「エラーになるもの」から始めます。400が消えてから、数字の動きを実測し、最後に運用面を確かめる流れです。

モデルIDを差し替える

最初の作業はIDの差し替えです。プラットフォームごとに表記が違うので、一括置換する前に、自分のコードがどの経路を使っているかを確かめます。

claude-haiku-5-5は日付サフィックスのない固定IDで、別名のエイリアスもありません。4.5のように日付付きIDと短縮IDを併用していた設定は、1つに揃えられます。移行元の仕様と退役日はClaude Haiku 4.5の仕様と料金にあります。Google Cloudは4.5で@20251001の形でしたが、5.5では日付なしになる点が、置換漏れの起きやすいところです。

トークンを測り直す

Haiku 5.5はClaude 4.7以降のモデルと同じ新しいトークナイザーを使います。同じ入力文でも、Haiku 4.5よりトークン数がおよそ30%増えます。増え幅は内容によって変わります。

リクエストやレスポンス、ストリーミングイベントの形は変わりません。変わるのは、トークンで測ったり予算を組んだりしている箇所すべてです。

• usageフィールドとトークンカウントの結果が、同じ文章でも大きくなる
• 同じトークン数に入る文章量が減る
• 4.5向けに決めたmax_tokensでは、同じ内容の出力が途中で切れることがある
• 4.5のトークン数から出したコスト試算は、5.5のトークン数と料金で出し直す

測り直しは、modelにclaude-haiku-5-5を指定してトークンカウントAPIを呼ぶ形で行います。4.5で測った数値に1.3を掛けるやり方では、内容による増え幅の違いが拾えません。

画像にも注意が要ります。Haiku 5.5は高解像度の画像区分を使い、長辺2,576ピクセルまたは4,784ビジュアルトークンを超える画像を縮小します。Haiku 4.5は長辺1,568ピクセルまたは1,568ビジュアルトークンが境目です。2,000×1,500ピクセルの画像は、5.5で4.5の約2.5倍のビジュアルトークンになります。画像を大量に流す処理は、文章より先に請求額が動きます。

料金表と合わせて見るとどうなるか

単価は逆向きに動きます。料金ページの入力単価は、Haiku 4.5が1MTokあたり$1、出力が$5です。Haiku 5.5は100,000トークンまでのプロンプトで入力$0.10、出力$0.50になります。

ただし5.5は、プロンプトが100,000トークンを超えるリクエストの単価が上がります。入力$0.50、出力$2.50です。この長さにはキャッシュの読み書きを含む全入力トークンが数えられ、一部がキャッシュにヒットしていても、超えたリクエストは高い単価になります。

つまり、トークン数が3割増えても、短いプロンプト中心なら単価の差が大きく効きます。長文を詰め込む処理は、閾値を超える頻度で採算が変わります。リクエストごとの入力トークン数の分布を取ってから、移行後のコストを試算すると外しにくくなります。

thinkingをadaptiveに変える

thinking: {"type": "enabled", "budget_tokens": N}は、Haiku 5.5では400エラーになります。4.5向けのリクエストはこの形でした。

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

5.5ではadaptive thinkingに替え、考える量はoutput_config.effortで決めます。次の形が、公式の移行ガイドに載っている書き換え例です。

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

adaptive thinkingは既定でオンです。thinkingを指定しないリクエストでも、レスポンスの先頭にthinkingブロックが1つ以上付くことがあります。thinkingは未指定のままか{"type": "adaptive"}にして、考える量はeffortで動かします。

effortの選び方

Haiku 5.5はHaikuとして初めてeffortの段階を持ち、既定はmediumです。4.5でthinkingを使っていなかった処理、または小さい予算で節約していた処理は、低いeffortから試します。

lowは最も安く速い反面、長いエージェントのプロンプトでは検索を飛ばす、早く止まる、確認を省くといった挙動が出やすくなります。xhighとmaxでは思考も返答もかなり長くなるため、Claude Sonnet 5.5でも同じ評価を回して、性能・コスト・速度を比べる運用が勧められています。

thinkingを無効にしていたプロンプトをeffortで調整し直す流れは、Claude Opus 5.5でthinking無効のプロンプトを移行する手順にもあります。

thinkingまわりで起きる5つの変化

budget_tokensを消すだけでは拾えない変化があります。

• max_tokensを食う: thinkingのトークンはmax_tokensに含まれます。小さい値のままだと、thinkingブロックのあと本文が出る前にstop_reason: "max_tokens"で止まります。値を上げるか、effortを下げます
• thinkingブロックの内容が空: 既定では、thinkingフィールドが空でsignatureだけが返ります。4.5は要約済みの思考を返していました。要約が欲しい場合はthinking: {"type": "adaptive", "display": "summarized"}と指定します
• 過去ターンのthinkingが入力に残る: 4.5は最新ターンのブロックだけを保持しましたが、5.5は過去ターンのブロックも文脈に残り、入力トークンに数えられます。マルチターンの会話では、トークナイザー由来の増加より入力が膨らみます。古いブロックを消したいときは、thinking block clearingを使います
• 強制tool_choiceでは思考しない: anyや名前指定のツール強制は受け付けますが、レスポンスはツール呼び出しから始まり、thinkingブロックがありません。ツールを呼ぶ前に考えさせたいなら、tool_choice: {"type": "auto"}にして、プロンプトでツールを使う場面を書きます
• 先頭ブロックを答えと決めつけない: レスポンスのcontentは、位置ではなくtypeで選びます

thinking: {"type": "disabled"}で思考を止めることもできますが、使えるのはlow・medium・highのときだけです。xhighとmaxと組み合わせると400になります。プロンプトで「直接答えて」と書いても思考は止まらなかった、という検証結果が記載されています。

返答の取り出し方を直す

先頭ブロックが答えだと決めているコードは、5.5で壊れやすい箇所です。Pythonなら、次のようにtypeで選びます。

text = "".join(
    block.text for block in response.content if block.type == "text"
)

ツール結果を返す往復では、thinkingブロックを加工せずそのまま戻します。ここを要約したり落としたりすると、後述の「前の内容を変えない」条件に引っかかります。

サンプリング引数を消す

Haiku 4.5が受け付けたtemperature・top_p・top_kは、5.5では3つとも指定しないのが基本です。挙動を変えたいときはプロンプトで誘導します。

細かい条件は次のとおりです。

• temperatureを含める場合は1でなければならない
• top_pを含める場合は既定の0.99でなければならない。1も400になる
• top_kは、どんな値でも400になる
• temperatureとtop_pを同時に含めるリクエストも400になる

既存コードに「決定的にしたいからtemperature: 0」という設定があれば、その箇所は必ず直します。ラッパー関数が引数を既定で付けている例が多いので、呼び出し側だけでなく、SDKの薄いラッパーも検索対象に入れます。

prefillをuserターンに置き換える

prefillは、messagesの最後にassistantのターンを置き、モデルにその続きを書かせる手法です。Haiku 4.5ではthinkingがオフのときだけ使えました。Haiku 5.5は、thinkingをオフにしていても400で拒否します。messagesはuserターンで終えます。

prefillを何のために使っていたかで、置き換え先が変わります。

継続の例は、公式の移行ガイドでは「Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.」の形で示されています。

廃止の背景と5つの移行先は、Claude 4.6でprefillが廃止された理由に詳しくあります。JSON出力を固めるためのprefillが主な用途なら、そちらの移行先の比較も参考になります。

computer useをtoolsetに移す

Haiku 4.5はcomputer_20250124ツールとcomputer-use-2025-01-24ベータヘッダーでcomputer useに対応していました。Claude APIとGoogle Cloudでは、Haiku 5.5はcomputer_toolset_20260801だけを受け付けます。computer_20250124を宣言したリクエストは400です。

Amazon Bedrockでは扱いが違います。computer_20250124は同じく受け付けられず、computer_20251124のツールバージョンとcomputer-use-2025-11-24ベータヘッダーを使います。

Claude API・Google Cloud向けの移行は、次の順です。

Claude APIとGoogle Cloudでは、5.5はbrowser_toolset_20260801のブラウザ利用ツールにも対応します。Haiku 4.5は対応していません。

会話の保存と再生を見直す

ここは、コードを直すだけでは済まない項目です。thinkingブロックの扱いが変わるため、会話ストアを持つサービスで影響が出ます。

別アカウントで再生しない。Haiku 5.5のthinkingブロックは、生成したアカウント、またはそれとリンクしたアカウントでだけ有効です。別のアカウントが送ると、APIはモデルに渡す前にそのブロックを落とします。リクエストは成功するので、推論が抜けたことに気づけません。1つの会話ストアで複数の顧客を捌くサービスは、会話を生成元のアカウントで再生します。

前の内容を書き換えない。Haiku 5.5のthinkingブロックが有効なのは、その前に送った内容が変わらない間だけです。system、tools、過去のmessagesを変えたうえでthinkingブロックを送り返すと、400になります。4.5にはこの検査がありません。会話はappend-onlyで運用します。

2026年8月31日00:00 UTCより前に作られたアカウントでは、thinking.block_binding.prefix_mismatch_behaviorを設定したリクエストでだけ、このエラーが返ります。

この制約は、プロンプトの運用にも響きます。システムプロンプトを更新してから、保存済みの会話を再開すると失敗することがあるためです。指示を途中で変えたいときは、最新のターンに入れます。

refusalを処理する

Haiku 5.5は安全分類器を動かしていて、リクエストを断ることがあります。断られたレスポンスはstop_reason: "refusal"を返し、stop_details.categoryにカテゴリーが入ります。

Haiku 4.5から移る場合、これらの拒否は新しい挙動です。5.5にはサーバー側のフォールバックがないので、クライアント側でrefusalを処理します。同じリクエストを再送しても、たいていまた拒否されます。

実装では、停止理由の分岐にrefusalを足し、categoryをログに残します。セキュリティ業務でcyberに誤って当たる場合は、Cyber Verification Programへの申請という経路があります。生命科学の業務でbioに当たる場合は、Life Sciences Verification Programです。

Priority TierとBedrockの制約

運用契約の面では2点あります。

• Priority Tier: Haiku 4.5でPriority Tierを契約している組織は、5.5での容量を別に計画します。Haiku 5.5はPriority Tier非対応です
• Bedrockのstructured outputs: Amazon Bedrockでは、Haiku 5.5でstructured outputs(output_config.formatやstrict: trueのツール)が使えません。形式をプロンプトで説明するか、strictのないツールを使い、出力はコード側で検証します

prefillの置き換え先にstructured outputsを選んでいる場合、Bedrock経由の構成だけは別の手当てが要る点に注意します。

Claude Codeで移行を進める

コードベースが大きいときは、Claude Codeに作業の大半を任せられます。公式の移行ガイドでは、/claude-api migrateで同梱のClaude APIスキルを呼ぶ方法が案内されています。

/claude-api migrate this project to claude-haiku-5-5

スキルは、モデルIDの差し替え、必要な破壊的パラメーター変更、prefillの置き換え、effortの調整を作業ディレクトリ全体に適用し、人が確認すべき項目のチェックリストを出します。編集の前に、移行範囲(作業ディレクトリ全体・サブディレクトリ・ファイル一覧)の確認を求め、BedrockやClaude Platform on AWSのクライアントも検出してID形式を調整します。

自動置換のあとは、取りこぼしを機械的に探します。次のコマンドで、400の原因になる文字列が残っていないかを確かめられます。

grep -rnE \
  "budget_tokens|temperature|top_p|top_k|computer_20250124" \
  --include="*.py" --include="*.ts" --include="*.json" src/

ヒットした箇所は、5.5向けの分岐に含まれるものか、4.5用に残すものかを見分けます。複数モデルを切り替えるアプリでは、モデルごとにリクエストを組み立てる関数を分けておくと、分岐の漏れが減ります。

Claude Codeに規約として覚えさせるなら、CLAUDE.mdに次のような断片を置く方法があります。例示であり、公式の記載ではありません。

## Claude Haiku 5.5向けのAPI呼び出し規約
- thinkingは未指定か {"type": "adaptive"}。budget_tokensは使わない
- temperature / top_p / top_k はリクエストに含めない
- messagesの最後はuserターン。assistantのprefillは書かない
- 応答はblock.typeで選ぶ。content[0]を答えとして読まない
- stop_reasonがrefusalのときはstop_details.categoryをログに出す

この規約があると、新しく生成されるAPI呼び出しも5.5の制約に沿いやすくなります。Claude Code側でもhaikuの指す先がHaiku 5.5に変わった版があり、経緯はClaude Code v2.1.293のリリースノートにあります。

移行後に回す確認の順序

置換が済んだら、次の順で確かめると原因を切り分けやすくなります。

1. 400が出ないか、既存のテストを5.5向けのモデルIDで流す
2. 代表的なプロンプトで、usageのトークン数を4.5と並べる
3. effortをlowとmediumで比べ、品質とコストの釣り合いを見る
4. 本番相当のデータでstop_reasonの分布を取り、refusalとmax_tokensの割合を確かめる

3と4は4.5では存在しなかった軸なので、移行前のベースラインがありません。切り替える前に、4.5でも同じ集計を取っておくと比較が成立します。

Haiku 3.5以前から移る場合

Haiku 3.5はClaude APIとAmazon Bedrockで退役済みです。Haiku 3はClaude APIとGoogle Cloudで退役済みで、退役したモデルへのリクエストは失敗します。Google CloudではHaiku 3.5が非推奨扱いで、既存顧客だけが使えます。

この場合は、ここまでの全項目に加えて、次の変更をします。

まとめ

Haiku 5.5への移行で壊れるのは、リクエストの形そのものが変わった4か所(thinking・サンプリング引数・prefill・computer use)です。ここは400が教えてくれます。本当に手間がかかるのは、エラーにならない側です。トークン数の3割増、単価の下落、100,000トークンを超えたときの値上がり、thinkingブロックの保存。これらは移行後の実測でしか見えません。

先に4.5でトークン数とstop_reasonの分布を取り、5.5のモデルIDで同じ集計を取り直します。差が小さければそのまま切り替え、refusalやmax_tokensが目立つなら、effortとmax_tokensから調整するのが手戻りの少ない順序です。