Claudeプロンプトキャッシュの使い方：5分/1時間の損益分岐と実測値

Claudeのプロンプトキャッシュ（公式ドキュメントの表記は「プロンプトキャッシング」）は、リクエストの先頭からcache_controlの目印までを保存し、次のリクエストで同じ先頭部分が届いたときに安い単価で読み直す仕組みです。先頭部分はtools→system→messagesの順に並べたもので、目印より前が1文字でも違えば別物として扱われます。2026年10月30日時点の料金では、書き込みが基本入力単価の1.25倍（5分）または2倍（1時間）、読み取りはOpus 5.5とSonnet 5.5が0.05倍、Fable 5.1が0.025倍、Haiku 5.5が0.1倍です。

今日から使うなら、複数ターンの会話ではリクエストのトップレベルに"cache_control": {"type": "ephemeral"}を1つ足す自動キャッシュから始めます。毎回変わる部分（日時やユーザーの質問）が後ろに付くプロンプトでは、変わらない最後のブロックに目印を置く明示的ブレークポイントを使います。効いたかどうかは、レスポンスのusageにあるcache_read_input_tokensが0より大きいかで判断します。2026年10月30日にLaoZhang経由でSonnet 5.5を呼んだ実測では、7,882トークンのsystemプロンプトが1回目に書き込まれ、2回目と3回目は7,882トークンすべてが読み取りになりました。

ただし、目印より前が512トークン（5.5世代とFable 5.1の最小値）に届かないと、エラーも出ずに何もキャッシュされません。また、1回しか送らないプロンプトや、TTL（有効期間）より長い間隔で送る呼び出しでは、書き込みの割増分だけキャッシュなしより高くなります。

プロンプトキャッシュの仕組み：目印までの先頭部分を再利用

キャッシュの単位は、リクエストの先頭から目印（キャッシュブレークポイント）までのプレフィックスです。Anthropicのプロンプトキャッシング解説によると、キャッシュを有効にしたリクエストが届くと、目印までのプレフィックスが最近保存されていないかを確かめ、あれば再利用し、なければ全体を処理して応答が始まった時点でプレフィックスを保存します。キーは目印までの内容全体のハッシュなので、toolsの定義を1か所変えるだけで、その後ろにあるsystemとmessagesのキャッシュも使えなくなります。

有効期間はデフォルトで5分で、キャッシュが読まれるたびに追加料金なしで延長されます。期間はリクエストの開始時点から数えるため、4分かけてストリーミングした応答のあとは残り約1分しかありません。ヒットには目印までのテキストと画像が100%一致している必要があり、Claude APIではキャッシュがワークスペースごとに分かれていて、別の組織と共有されることもありません。キャッシュを使っても出力は変わらず、キャッシュなしと同じ応答が返ります。

キャッシュできるのは、toolsのツール定義、systemのブロック、userとassistantのテキスト、userターンの画像や文書、tool_useとtool_resultです。thinkingブロックには直接目印を付けられませんが、前のassistantターンに含まれていればほかの内容と一緒にキャッシュされ、読み取られたときは入力トークンとして数えられます。引用（citations）の部分ブロックや空のテキストブロックは対象外で、引用を使うなら元の文書ブロックをキャッシュします。

有効にする方法：自動キャッシュと明示的ブレークポイント

どちらを使うかは、プロンプトのどこが毎回変わるかで決まります。会話を毎ターン後ろに足していく使い方なら自動キャッシュ、長いsystemプロンプトや資料は同じで最後の質問だけが毎回違う使い方なら明示的ブレークポイントです。Anthropicも複数ターンの会話では自動キャッシュから始めることを勧めています。料金、最小トークン数、20ブロックの遡り範囲はどちらも同じで、両方を同じリクエストで併用することもできます。

自動キャッシュ：リクエスト直下にcache_controlを1つ置く

自動キャッシュでは、個々のブロックではなくリクエスト本文のトップレベルにcache_controlを1つ書きます。目印は最後のキャッシュ可能なブロックに自動で付き、会話が伸びるたびに後ろへ移動します。

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "社内規程に答えるアシスタントです。以下に規程の全文を貼ります……",
    "messages": [
      {"role": "user", "content": "経費精算の締め日はいつですか？"}
    ]
  }'

2026年10月30日にLaoZhang経由でSonnet 5.5へ3ターンの会話を送ったところ、1ターン目は7,906トークンの書き込み、2ターン目は7,906トークンの読み取りと65トークンの書き込み、3ターン目は7,971トークンの読み取りと74トークンの書き込みでした。前のターンまでが読み取りになり、新しく足した分だけが書き込まれていて、目印が後ろへ移る様子がそのまま数字に出ています。1時間にしたい場合は{"type": "ephemeral", "ttl": "1h"}と書きます。

注意したいのは、最後のブロックが毎回変わる1問1答型の使い方です。自動キャッシュは目印を最後のブロック、つまり毎回違うユーザーの質問に置くため、Anthropicの公式APIでは毎回書き込みが発生し、読み取りにはなりません。この形なら次の明示的ブレークポイントを使います。

明示的ブレークポイント：変わらない最後のブロックに目印を置く

明示的ブレークポイントでは、キャッシュしたい範囲の最後のブロックにcache_controlを直接付けます。systemを配列にして、毎回同じ内容の最後のブロックに目印を置くのが基本形です。

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "system": [
    {"type": "text", "text": "社内規程に答えるアシスタントです。"},
    {
      "type": "text",
      "text": "（規程の全文。毎回同じ内容）",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "2026年10月30日 14:05 経費精算の締め日はいつですか？"}
  ]
}

日時が入ったユーザーメッセージに目印を置くと、毎回ハッシュが変わります。キャッシュの書き込みは目印の位置でしか起こらず、遡って探すのは過去に書き込まれた位置だけなので、手前の規程部分も読み取りになりません。2026年10月30日のLaoZhang経由の実測では、規程の代わりに7,882トークンの記事をsystemに置いて目印を付け、違う質問を3回送ったところ、書き込み7,882、読み取り7,882、読み取り7,882という結果でした。

目印は1リクエストに4つまで置けて、置くこと自体に料金はかかりません。ツール定義はほとんど変えず資料は毎日更新する、というように変わる頻度が違う部分を分けたいときや、会話が長く伸びて前回の書き込み位置から20ブロック以上離れそうなときに、2つ目以降の目印を使います。systemに明示的な目印を付け、会話部分はトップレベルの自動キャッシュに任せる併用もできます。

モデル別の料金：書き込み1.25倍・2倍、読み取り0.025〜0.1倍

2026年10月30日時点のAnthropicのプロンプトキャッシング料金表では、書き込みは全モデル共通で基本入力単価の1.25倍（5分）と2倍（1時間）ですが、読み取りの倍率はモデルによって違います。「読み取りは1/10」はHaiku 5.5と旧モデルにしか当てはまりません。単価は100万トークンあたりの米ドルで、最小トークン数はClaude APIでの値です。

Opus 5.5とSonnet 5.5では、書き込み（1.25倍）と読み取り（0.05倍）の差は12.5倍ではなく25倍です。「最小1,024トークン」もSonnet 5や4.6などの旧モデルの値で、現行の5.5世代とFable 5.1は512トークンからキャッシュされます。Haiku 5.5はプロンプトの長さで単価が変わるモデルで、キャッシュの読み取り分と書き込み分もプロンプトの長さに数えられます。キャッシュ分を含めて10万トークンを超えると、表の「Haiku 5.5（10万トークン超）」の行の単価になります。

実際にいくら減るかは、プレフィックスの長さと呼び出し回数で計算できます。8万トークンの資料を有効期間内に20回使う場合、入力側の費用は書き込み1回と読み取り19回の合計です。Sonnet 5.5の5分キャッシュなら80,000×$2.50/100万＋19×80,000×$0.10/100万＝$0.20＋$0.152＝$0.352で、キャッシュなしの$3.20より89.0%少なくなります。同じ条件でFable 5.1は$16.00が$1.38（91.4%減）、Opus 5.5は$6.40が$0.704（89.0%減）、Haiku 5.5は$0.16が$0.025（84.2%減）です。1時間キャッシュでは書き込みが2倍になるぶん、Sonnet 5.5で$0.472（85.2%減）になります。出力トークンの料金はキャッシュの有無で変わりません。

Sonnet 5.5の読み取りは2026年10月7日に$0.20から$0.10へ下がっていて、請求への影響は「Claude Sonnet 5.5のキャッシュ読み取り料金は$0.10：削減率の求め方」で計算できます。モデルごとの単価全体は「Claude Fable 5.1のAPI料金：単価と月額の目安」と「Claude Opus 5.5の料金と上限リセット権：API単価、使える枠、確認手順」で確認できます。

5分と1時間はどちらが得か：呼び出し間隔で決まる損益分岐

同じプレフィックスを5分以内の間隔で使い続けるなら5分、5分を超えて1時間以内の間隔で使うなら1時間を選びます。5分キャッシュは読まれるたびに無料で延長されるので、間隔が5分以内に収まる限り、2倍の書き込み料金を払う理由はありません。間隔が1時間を超える場合はどちらのTTLでもキャッシュが残らず、毎回書き込み料金を払うことになります。Anthropicの説明では、5分と1時間で応答速度の違いはありません。

損益分岐は倍率だけで計算できます。すべての呼び出しが有効期間内なら、5分キャッシュは2回目からキャッシュなしより安くなり、Opus 5.5とSonnet 5.5では書き込み1.25＋読み取り0.05＝1.30が、キャッシュなし2回分の2.00を下回ります。Haiku 5.5（1.25＋0.1＝1.35）とFable 5.1（1.25＋0.025）も同じく2回目からです。1時間キャッシュは2回では2＋0.05＝2.05でキャッシュなしの2.00をわずかに上回り、3回目で2＋0.05×2＝2.10がキャッシュなしの3.00を下回ります。

間隔が5分を超えるときにTTLの選び方で差が出ます。10万トークンのプレフィックスをSonnet 5.5で10分おきに1時間で6回送る場合、キャッシュなしは6×100,000×$2/100万＝$1.20です。5分キャッシュは毎回期限が切れて書き込み直しになるので6×$0.25＝$1.50と25%高くなり、1時間キャッシュは書き込み$0.40＋読み取り5×$0.01＝$0.45で62.5%安くなります。

2026年10月30日にLaoZhang経由で試したところ、有効期間の境界はドキュメントどおりでした。5分キャッシュは書き込みから6秒後に読み取りになりましたが、6分20秒何も送らずに待つと次の呼び出しは7,882トークンの書き込み直しになりました。"ttl": "1h"を付けたキャッシュは、7分空けたあとも7,882トークンの読み取りでした（1時間の上限までは試していません）。5分と1時間を1つのリクエストで併用する場合は、1時間の目印を5分の目印より前に置く必要があります。

キャッシュでかえって高くなる3つの場合

1つ目は、同じプレフィックスを1回しか送らない場合です。キャッシュ部分には基本入力単価の1.25倍（5分）か2倍（1時間）を払うので、読み取りが一度もなければその分だけ損になります。Sonnet 5.5で7,882トークンのプレフィックスなら、キャッシュなしの入力は約$0.0158、5分の書き込みは約$0.0197、1時間の書き込みは約$0.0315です。

2つ目は、TTLより長い間隔で送る場合です。5分キャッシュを10分おきの呼び出しに使うと毎回期限が切れて書き込み直しになり、キャッシュなしより25%高くなります。呼び出しの間隔を記録して5分を超えることが多いなら、1時間に切り替えるか、キャッシュを外します。

3つ目は、キャッシュがまだない状態で同じリクエストを並列に送る場合です。キャッシュは最初の応答が始まってから使えるようになるため、2026年10月30日にLaoZhang経由でSonnet 5.5へ同じリクエストを3つ同時に送ったところ、3つとも7,882トークンの書き込みになり、読み取りは0でした。書き込み3回は$0.0591、1回書き込んで残り2回を読み取りにできれば$0.0213です。並列処理を始める前に1件だけ送り、その応答が返り始めてから残りを送ると、2件目以降が読み取りになります。

キャッシュヒットの確認：usageの3つのフィールドと実測値

ヒットしたかどうかは、レスポンスのusage（ストリーミングではmessage_startイベント）にある3つのフィールドで分かります。入力トークンの合計はcache_read_input_tokens＋cache_creation_input_tokens＋input_tokensで、input_tokensだけを見ると入力が極端に少なく見えるので注意します。

下の値は、2026年10月30日にLaoZhangのAnthropic形式のエンドポイント（https://api.laozhang.ai/v1/messages）経由でclaude-sonnet-5-5を呼んだときのものです。systemには英語の技術記事1本（7,882トークン）を置いて明示的な目印を付け、effortはlow、max_tokensは60にしました。1アカウントで1日、プレフィックス1種類の結果です。この日は設定を変えたテストを含めて計51回呼び出し、費用は合計$0.471でした。

注記：laozhang.ai は当ブログ運営チームの自社サービスです。その料金は中立的な比較ではなく、自社の提示価格です。

ヒット率は「読み取り÷（読み取り＋書き込み＋input_tokens）」で出せます。上の2回目なら7,882÷（7,882＋0＋16）＝約99.8%です。1日分の請求を見積もるなら、呼び出しごとの率を平均するのではなく、3つのフィールドをそれぞれ合計してから割ります。

cache_creation_input_tokensとcache_read_input_tokensが両方0なら、そのリクエストはキャッシュされていません。同じLaoZhang経由の実測では、Sonnet 5.5で目印より前が180トークンと377トークンのプロンプトは2回とも両方0で、HTTP 200のままエラーも警告も出ませんでした。567トークンと1,094トークンのプロンプトは1回目に書き込まれ、2回目に読み取りになっています。Claude APIで1時間キャッシュを使った場合は、usage.cache_creationの中にephemeral_5m_input_tokensとephemeral_1h_input_tokensの内訳も付き、その合計がcache_creation_input_tokensに等しくなります。

キャッシュがヒットしないときのチェックリスト

Claude APIを直接使っているなら、最初にキャッシュ診断（cache diagnostics）を試します。1ターン目のリクエストに"diagnostics": {"previous_message_id": null}を、2ターン目以降には前回のレスポンスのidを入れると、レスポンスのdiagnosticsに、モデル、system、tools、messagesのどこでプレフィックスが食い違ったかが返ります。diagnosticsがnullなら食い違いはありません。2026年10月30日時点のAnthropicのキャッシュ診断ドキュメントでは、Fable 5.1、Opus 5.5、Sonnet 5.5、Haiku 5.5などが対象で、対応はClaude APIのみです。診断が使えない経路では、次の項目を上から確認します。

• cache_creation_input_tokensとcache_read_input_tokensが両方0なら、目印より前がモデルごとの最小トークン数（料金表の右端の列）に届いていません。少し足りないだけなら、固定の資料や例を足して最小値を超えた方が、頻繁に使うプロンプトでは安くなります。
• 毎回書き込みばかりで読み取りが0なら、目印が日時やユーザーの質問など毎回変わるブロックに付いています。自動キャッシュで1問1答をしている場合も同じで、変わらない最後のブロックに明示的な目印を移します。
• 目印より前の何かが変わっていないかを確かめます。ツール定義の変更はtools・system・messagesのすべてを、Web検索や引用、高速モード（speed）の切り替えはsystemとmessagesを、tool_choiceの変更や画像の追加・削除はmessagesを無効にします。thinkingの設定とoutput_config.effortの変更はmessagesを必ず無効にし、toolsとsystemへの影響はモデルによって違います。2026年10月30日のLaoZhang経由の実測では、Sonnet 5.5のeffortをlowからmedium、lowへと戻しても、systemのキャッシュは読み取りのままでした。
• 5.5世代とFable 5.1で会話の途中にシステム指示を足すなら、トップレベルのsystemを書き換えず、messagesに{"role": "system"}のメッセージを追加します。こうするとキャッシュ済みのプレフィックスが変わりません。
• 途中でモデルを替えていないかを確かめます。キャッシュはモデルごとに別で、同日のLaoZhang経由の実測では、Sonnet 5.5で読み取りになっていた同じ7,882トークンをclaude-opus-5-5に送ると書き込みからやり直しになり、2回目のOpus呼び出しで初めて読み取りになりました。
• 前回の呼び出しから5分（1時間キャッシュなら1時間）以上空いていないか、キャッシュがない状態で並列に送っていないかを確かめます。
• 別のワークスペースのAPIキーを使っていないかを確かめます。Claude APIではキャッシュがワークスペースごとに分かれています。
• SwiftやGoでtool_useブロックを組み立てている場合は、JSONのキーの順番が実行ごとに変わっていないかを確かめます。順番が変わるだけでハッシュが一致しなくなります。
• 会話が長い場合は、前回の書き込み位置から20ブロック以上進んでいないかを確かめます。遡って探すのは20ブロックまでなので、途中に2つ目の目印を置いておきます。

ゲートウェイやOpenAI互換エンドポイント経由でも効くか

ゲートウェイ経由でもキャッシュは効きますが、cache_controlをそのまま転送するか、どの単価で課金するかはゲートウェイ次第なので、自分の経路でusageと請求額を確かめる必要があります。2026年10月30日にLaoZhang経由で試した範囲では、エンドポイントをhttps://api.laozhang.ai/v1/messagesに、認証ヘッダーをAuthorization: Bearer $LAOZHANG_API_KEYに替えるだけで、リクエスト本文は公式APIと同じ形のままキャッシュが働きました。51回分の請求額$0.471は、記録したusageを公式の書き込み・読み取り単価で計算し直した$0.469とほぼ一致しています。

注記：laozhang.ai は当ブログ運営チームの自社サービスです。その料金は中立的な比較ではなく、自社の提示価格です。

一方で、Anthropicのドキュメントにない挙動もありました。cache_controlをどこにも付けていないリクエストでも、7,882トークンのsystemプロンプトが1回目に書き込まれ、2回目に読み取りになりました。日時入りのユーザーメッセージに目印を置いた場合も、system部分の7,882トークンは読み取りになっています。ゲートウェイかその上流の経路がsystemプロンプトに自動でキャッシュ指定を付けていると考えられますが、Anthropicの公式APIに直接送った場合とは比べていません。課金にも表れていて、cache_controlなしの1回目は5分の書き込み単価で1.9788セントかかり、キャッシュなしの単価なら1.5846セントだったので25%高くなっています。同じリクエストの2回目は0.0872セントでした。長いsystemプロンプトを1回だけ送る用途ではその分割高になり、繰り返し送る用途ではコードを変えなくても安くなります。

ほかにも、"ttl": "1h"は7分後も読み取りになって機能していましたが、レスポンスにusage.cache_creationの内訳が付かないため、usageだけでは5分と1時間の書き込みを区別できません。diagnosticsを送ってもHTTP 200のまま何も返らず、systemを変えた2ターン目の書き込み（7,890トークン）の理由は分かりませんでした。

OpenAI互換の/v1/chat/completionsでclaude-sonnet-5-5を呼んだ場合は、キャッシュ関連のフィールドを何も送らなくても、1回目のprompt_tokens_details.cached_creation_tokensが7,882、2回目のprompt_tokens_details.cached_tokensが7,882でした。この形式のprompt_tokens（どちらも7,893）はキャッシュ分を含んだ合計なので、cached_tokensを足し直すと二重に数えることになります。同じレスポンスにはAnthropic形式のcache_creation_input_tokensやcache_read_input_tokensも入っていました。

事前ウォームアップ：max_tokens 0でキャッシュだけ書く

ユーザーが最初の質問を送る前にキャッシュを作っておきたいなら、max_tokens: 0のリクエストを送ります。Anthropicのドキュメントでは、APIは目印の位置にキャッシュを書き込み、空のcontentとstop_reason: "max_tokens"を返し、出力トークンは課金されません（書き込み料金はかかります）。目印は本番のリクエストと共通のsystemやツール定義に置き、仮のユーザーメッセージには置きません。thinkingの設定とeffortも本番と同じにするので、自動キャッシュではなく明示的ブレークポイントを使います。

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 0,
  "system": [
    {
      "type": "text",
      "text": "（本番と同じsystemプロンプト）",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "warmup"}]
}

max_tokens: 0は、stream: true、thinking.type: "enabled"、構造化出力、tool_choiceがtoolまたはanyのいずれかを指定しているとinvalid_request_errorで拒否され、Message Batchesの中でも使えません。以前から使われてきたmax_tokens: 1の方法より、こちらが推奨されています。

ゲートウェイ経由では結果が違うことがあります。2026年10月30日にLaoZhang経由でmax_tokens: 0を送ると、空の応答ではなく46トークンの通常の回答（stop_reason: "end_turn"）が返り、キャッシュは書き込まれていました。max_tokens: 1なら出力1トークンで7,882トークンが書き込まれ、続く本番リクエストは読み取りになっています。ウォームアップの応答のstop_reasonとoutput_tokensを一度確認し、0が通常の生成として扱われる経路では1を使います。

Claudeプロンプトキャッシュのよくある質問

Claude Codeのキャッシュは自動ですか？有効時間はどのくらいですか？

Claude Codeはプロンプトキャッシュを自動で管理するので、cache_controlを書く必要はありません。2026年10月30日時点のClaude Codeのプロンプトキャッシング解説では、Claudeのサブスクリプションをプランの使用量の範囲で使っているとメインの会話は1時間、APIキーや利用クレジット、クラウド事業者経由では5分です。1回のターンが急に高くなる理由の切り分けは「Claude Code のキャッシュミスと token コスト：1 回の turn が急に高く見える理由」で確認できます。

Claude APIのキャッシュヒットはレート制限に数えられますか？

Anthropicの1時間キャッシュの説明には、キャッシュヒットはレート制限から差し引かれないと書かれています。429が出たときにどの制限に当たっているかは「Claude API の Rate Limit Reached は、先に制限の持ち主を特定する」で確認できます。

プロンプトキャッシュを使うとClaudeの回答は変わりますか？

変わりません。Anthropicのドキュメントでは、プロンプトキャッシュは出力の生成に影響せず、キャッシュを使わない場合と同じ応答が返るとされています。

Amazon BedrockのClaudeでもプロンプトキャッシュは使えますか？

使えますが、条件が違います。Opus 4.6以前向けの旧Bedrock連携ではトップレベルのcache_control（自動キャッシュ）が400エラーになるため、明示的ブレークポイントを使います。最小トークン数やusageのフィールド名はAWSのBedrockドキュメントに従い、キャッシュはワークスペースではなく組織単位で分離されます。1時間キャッシュはBedrockでも使えます。