Claude APIのキャッシュが壊れる変更は、compactionの直後に入れる

Claude APIでキャッシュを壊す変更は、会話の途中ではなくcompactionの直後の最初のリクエストで入れます。長い会話では接頭辞が大きく、壊れた1ターンの書き直し代がモデルによっては読み取りの25〜50倍になるためです。

キャッシュが何をきっかけに外れたかを調べる方法はCache diagnosticsでキャッシュミスの原因を特定するにあります。ここで扱うのは、外れたときにいくら払うのかと、壊れる変更をいつ入れれば安く済むのかです。

壊れた1ターンはモデルごとにいくらかかるか

100,000トークンの接頭辞で、5分キャッシュのまま1ターンだけ壊れた場合の費用は次のとおりです。公式の料金から計算した値で、実測ではありません。

上記以外の現行モデルでは12.5倍です。

壊れると接頭辞全体が書き込み単価(入力の1.25倍)で課金され、読み取り単価では課金されません。読み取りが安いモデルほど、壊れたときの落差が大きくなります。Fable 5.1の読み取りは入力の0.025倍なので、壊れた1ターンの倍率が最も高く出ます。

1回あたりは数十セントでも、エージェントのループは1セッションに数十ターンを重ねます。毎ターン壊れる設計は、キャッシュを無効にした運用より高くつくことさえあります。

リクエストごとに変わる文字列を先頭に置かない

最もありがちな壊し方は、時刻や待ち行列の位置のような毎回変わる文字列を、system promptの先頭に置くことです。キャッシュは、tools、system、messagesの順に並んだリクエストのバイト単位の接頭辞一致で判定されます。先頭が毎回変わると、後ろがどれほど同じでも全体が書き込みになります。

公式の計測は、バグ報告を振り分ける小さなエージェントで行われています。Claude Sonnet 5で、5分キャッシュ、1設定あたり3回の実行です。

• system promptの先頭に25トークンのステータス行を置いた場合、1回の実行が平均$4.24(3回の範囲は$4.12〜$4.47)で、キャッシュからの読み取りはゼロでした
• 同じ行を最新のユーザーターンの末尾、最後のキャッシュブレークポイントより後ろに置いた場合は$0.59($0.55〜$0.61)でした

先頭に置いた場合の費用は、キャッシュを切った同じ仕事より高くなっています。後日の再実行でも$4.28と$0.61で、結果は再現しています。

毎回変わる文字列は、最新のユーザーターンの中、最後のブレークポイントより後ろに置きます。

何を変えると、どこから先が壊れるか

接頭辞の途中で何かを変えると、その位置以降のキャッシュが外れます。プロンプトキャッシュの公式ページが挙げる変更と影響範囲のうち、運用で触りやすいものを抜き出します。✘は無効化、✓は有効のままです。

effortを変えると、messagesのキャッシュは必ず外れます。tools側とsystem側への影響はモデルによって違います。影響が一番大きいのは、ツールの追加です。ツール定義はキャッシュ対象の最も前にあり、変えると会話全体が書き直しになります。

effortを既定値と同じ値で明示しても、省略した場合と同じ扱いで無効化されません。出力形式を変えた場合も、その会話のキャッシュが無効になります。

変更はcompactionの直後の最初のリクエストで入れる

壊れることが避けられない変更は、キャッシュがどのみち作り直しになる場所へ寄せます。その場所がcompaction(会話の要約による圧縮)の直後です。計測では、同じ変更をcompaction後の最初のリクエストに寄せた群が最も安くなりました。

公式の計測は次のとおりです。バグ報告エージェントの長いセッションで、Claude Sonnet 5、5分キャッシュ、費用はusageフィールドから公式料金で計算されています。compactionは、プロンプトが80,000トークンを超えた時点(多くはリクエスト21〜25番目)で走りました。

同じ2つの変更でも、入れる位置で$0.75から$0.95まで動きます。途中で入れた場合、キャッシュの書き直しだけで1セッション$0.23を払っていました。途中で入れた群と直後に入れた群の差は$0.20で、95%信頼区間は$0.11〜$0.29です。各群は5セッション前後の平均なので、費用差の信頼区間は広めです。

「変更なし」の$0.81が直後の$0.75より高い点は、キャッシュの話ではありません。変更なしの群だけが既定のeffortで通しており、ほかの3群は低いeffortから始めています。変更なしの群では2セッションがもう一度compactionを走らせていました。そのため変更なしの群の高さは、effortと2回目のcompactionによるもので、書き直しの差は$0.01未満でした。

compactionを起こしたリクエストで変えてはいけない理由

「compactionのタイミングなら同じだろう」と、要約を起こすリクエストそのものに変更を載せるのは不利です。同じ計測では、この群のcompactionの要約パスが81,000トークンのコンテキストをキャッシュから読まず、書き込みました。そのパスの費用は$0.21で、変更を直後に回した群の同じパスは$0.04でした。

変更を入れる順序は次のとおりです。

compactionのキャッシュ設計そのものは、Compactionとプロンプトキャッシュを両立させるcache_controlの置き方で扱っています。オンデマンドで好きな時点に要約させる方法はオンデマンドcompactionの記事にあります。

壊さずに変えられる手段もある

最近のモデルでは、接頭辞を編集せずに設定を変える経路があります。変更を会話の末尾へ追記する形なので、compactionを待たなくても済む場合があります。

• 指示の追加: トップレベルのsystemを編集する代わりに、messagesの末尾へ{"role": "system"}メッセージを追加します。Fable 5.1、Mythos 5.1、Opus 5.5、Sonnet 5.5、Haiku 5.5などが対象で、Sonnet 5では使えません
• effortの変更: role: "system"メッセージのoutput_config.effortで指定します。Fable 5.1、Mythos 5.1、Opus 5.5、Sonnet 5.5、Haiku 5.5などで接頭辞が保たれます。ベータ機能で、mid-conversation-output-config-2026-07-01のヘッダーが必要です
• ツールの追加・変更: inline-tools-2026-09-15ヘッダーを付け、tool_additionブロックをrole: "system"メッセージに入れます。詳細はmid-conversationのツール変更の記事にあります

effortの切り替えは次の形です(公式の例に沿ったもので、環境のキーを入れてモデル名を合わせます)。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mid-conversation-output-config-2026-07-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 4096,
    "output_config": {"effort": "high"},
    "messages": [
      {"role": "user", "content": "移行手順を3ステップで"},
      {"role": "assistant", "content": "1. 書き出し 2. スキーマ作成 3. 取り込み"},
      {"role": "system", "content": [], "output_config": {"effort": "low"}},
      {"role": "user", "content": "1文で要約して"}
    ]
  }'

注意点が2つあります。ツール結果だけを持つユーザーターンは新しい入力に数えられないので、ツール利用ループの途中に置いたeffort変更は、次の新しい入力を持つユーザーターンまで待ちます。また、ツール追加でもtools配列に非遅延ツールが1つもない場合は、最初の1回だけ全面的なキャッシュミスが出ます。

変更後に読み取りが落ちていないかを確かめる

変更を入れた直後は、読み取りの割合が落ちていないかをusageで確かめます。公式の目安では、エージェントのループの読み取り割合は中央値で84%、上位1割で94%以上です。80%を下回ったら、キャッシュを壊しているものを探します。

u = response.usage
total = u.cache_read_input_tokens + u.cache_creation_input_tokens + u.input_tokens
print(f"read share: {u.cache_read_input_tokens / total:.0%}")

割合が落ちたまま戻らないときは、cache diagnosticsで接頭辞がどこで分かれたかを調べます。調べ方はCache diagnosticsの記事のとおりです。

この数字をそのまま信じてよいか

この記事の費用表には2種類の数字があり、扱いが違います。

• モデル別の「壊れた1ターン」の表は、公式料金からの計算値です。測った値ではありません
• compactionのタイミング比較は、Claude Sonnet 5での実測です。Fable 5.1やOpus 5.5、Sonnet 5.5で同じ$0.75や$0.95になるとは限りません

実測は1設定あたり5〜6セッションで、バグ報告エージェント1種類の結果です。差の向きは明確でも、金額は自分のワークロードで再計測する前提で読みます。精度は、どの群でも試行ごとのばらつきの範囲内でした。

読み取りが25〜50倍の単価差を持つモデルを使うなら、設定を会話の途中で何度も動かす設計自体を見直す価値があります。モデルごとの単価と1時間キャッシュの損益は、1時間キャッシュはいつ使うべきかで比べています。