Claudeのプロンプトキャッシュの仕組み — API課金とサブスク上限、効き方の違い

Claudeのプロンプトキャッシュとは — 仕組みは1つ、効き方は2つ

プロンプトキャッシュは、直前のリクエストと先頭が一致する部分(プレフィックス)を再処理せず、キャッシュから読み直す仕組みです。システムプロンプトや長い会話履歴のように毎回ほぼ同じ内容を送る場面で、処理コストとレイテンシの両方を削れます。仕組みそのものはAPIでもサブスクリプションでも同じです。違うのは、その節約が請求書に出るか、利用上限の消費として出るかという一点だけです。

APIキーで直接叩く場合、キャッシュの節約はそのままトークン単価に反映されます。Claude CodeやWebのclaude.aiをサブスクリプションで使う場合、単価は表に出ず、5時間枠と週次上限の消費量が軽くなる形で節約が現れます。API課金とサブスクリプションでは、同じキャッシュでも効き方が変わります。仕組みのコード実装はAnthropic APIのPrompt Cachingを理解する、Claude Codeの利用上限への効き方の詳細はプロンプトキャッシュはClaude Codeの利用上限をどう軽くするかにまとめてあるので、実装や数値の細部はそちらを参照してください。

API課金でのプロンプトキャッシュ — 単価そのものが変わる

APIキーでの呼び出しは、キャッシュの読み書きがそのままトークン単価の変化として請求に乗ります。キャッシュを書き込む(新規にキャッシュへ登録する)ときは通常の入力トークンより高い単価がかかり、5分TTLで1.25倍、1時間TTLで2倍です。読み取り(既存のキャッシュを再利用する)ときは通常の入力トークンよりずっと安く、標準は0.1倍、Claude Fable 5.1とMythos 5.1だけは0.025倍という別枠の単価になります。Claude Fable 5.1のキャッシュ読み取り$0.25は、この0.025倍が実額でいくらになるかの具体例です。

キャッシュが効いたかどうかはレスポンスのusageフィールドで確認できます。cache_creation_input_tokensが書き込み分、cache_read_input_tokensが読み取り分です。両方が0なら、そのリクエストはキャッシュされていません。よくある原因は、キャッシュ対象のプレフィックスがモデルごとに決まる最小トークン数に届いていないことです。エラーは返らず、無言で通常課金にフォールバックするので気づきにくい落とし穴です。

最小トークン数はモデルで違います。Claude Sonnet 5は1,024トークン、Claude Opus 5・Claude Fable 5.1・Claude Mythos 5.1は512トークン、Claude Haiku 4.5は4,096トークンです。短いシステムプロンプトしか送っていないのにキャッシュが効かない場合は、まずこの下限に足りているかを疑うのが早道です。下限にわずかに届かないだけなら、キャッシュ対象のコンテキストを少し水増ししてでも閾値を超えたほうが、繰り返し呼び出す用途ではトータルで安くつきます。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {"type": "text", "text": "長いシステムプロンプト..."},
      {"type": "text", "text": "固定コンテキスト", "cache_control": {"type": "ephemeral"}}
    ],
    "messages": [{"role": "user", "content": "質問文"}]
  }'

cache_controlをどのブロックに置くかで、キャッシュされる範囲が決まります。既定のTTLは5分で、無料で自動延長されます。会話の間隔が5分を超えて空くなら、ttl: "1h"を指定する1時間キャッシュに切り替える判断になります。API課金の利用者が最適化すべき対象はここで、書き込みコストと再利用頻度のトレードオフをTTLの選択で調整します。

1時間TTLと5分TTLは同一リクエスト内で併用できますが、順序に制約があります。1時間TTLのブロックは、必ず5分TTLのブロックより前に置く必要があります。長期固定のシステムプロンプトを1時間で、ターンごとに変わる会話履歴を5分でキャッシュする構成が典型例で、順序を逆にすると想定どおりの単価で処理されません。

サブスクリプション(Claude Code / claude.ai)でのプロンプトキャッシュ — 利用上限の消費が変わる

Claude Codeは会話の全履歴を毎ターン送り直します。プロンプトキャッシュが効いていれば、その再送分はキャッシュ読み取りの単価で処理され、Pro・Max・Teamの5時間枠と週次上限の消費もその分だけ軽くなります。Pro・Maxのプラン利用者にとって、/usageのセッションコスト表示自体は課金に直結しません。課金と直結するのは上限の消費速度のほうです。

ここで、API課金にはない挙動が1つあります。既定のTTLが課金形態によって変わる点です。Claude Codeは、プランに含まれる利用枠の範囲内で動いているときは会話本体に1時間TTLを要求します。プラン枠を使い切って使用量クレジット(usage credits)に切り替わった瞬間、課金が発生する状態になるため、Claude Codeは自動的に5分TTLへ落とします。APIキーやクラウド経由のサインインでは、最初から5分TTLが既定です。1時間を維持したい場合はpromptCacheTtl設定かCLAUDE_CODE_PROMPT_CACHE_TTL環境変数で自分から指定します(Claude Code v2.1.242以降)。

つまり、プラン利用者が長時間セッションを離席で中断しても、プラン枠の範囲内である限りキャッシュは1時間近く生き延びます。使用量クレジットに入った途端、同じ離席が5分でキャッシュ切れになり、次のメッセージが会話全体を再処理する高コストなターンに変わります。

/usageを実行すると、セッションブロックにPrompt cache (main)という行が表示され(v2.1.251以降)、直近のリクエストのうち何%が入力トークンをキャッシュから読めたか、キャッシュミスの回数、現在キャッシュが温まっているかを確認できます。

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · warm (1h TTL, last activity 40s ago)

この行のwarm (1h TTL...)という表示自体が、いま自分がプラン枠の内側にいることの手がかりになります。使用量クレジットへ切り替わっていれば、ここは5分TTLに変わります。サブスク利用者が最適化すべき対象は単価ではなく、何がキャッシュを壊し、5時間枠・週次上限の消費を増やすかです。モデル切り替え・エフォートレベルの変更・fast modeのオンは会話キャッシュを全損させます。具体的な操作一覧と壊れない操作の対比は、Claude Codeの利用上限への効き方を扱った前掲記事に整理してあります。

1時間TTLが適用されるのは会話本体だけで、サブエージェントには適用されません。サブエージェントは親と別の会話を新規に始めるため、プラン枠の内側にいても既定は5分TTLです。長時間のサブエージェント処理を挟むワークフローでは、この5分の壁だけ先に切れることがあります。

プロンプトキャッシュはAPI課金とサブスク上限をどう分けて動くか

書き込み単価・読み取り単価・TTLという同じ3つの変数が、課金形態によって現れ方を変えます。API課金では3つとも請求額に直結し、開発者はコード側でcache_controlとTTLを設計します。サブスク課金ではプラン枠の内側にいる限り単価は隠れ、TTLの既定値だけが1時間に伸びて、開発者ではなく利用者の操作パターンが消費速度を左右します。使用量クレジットに入った瞬間、Claude CodeはAPI課金と同じ5分TTL・同じ単価構造に合流します。1つの仕組みが、境界線をまたぐごとに違う顔を見せる格好です。

この境界線は、Max・Team・Enterpriseのプレミアムシートで週次上限の最大50%をFableモデルに充てられる仕組みとも接続しています。プラン枠の内側で動いている間はキャッシュのTTLもコストも意識せずに済み、外に出た瞬間に両方が牙を剥きます。プランの枠と使用量クレジットの関係はClaude料金プラン比較にまとめてあります。

API利用者とサブスク利用者、それぞれ何を最適化すべきか

API利用者はコードを書く側なので、cache_controlをどのブロックに置くか、5分と1時間のどちらのTTLを選ぶかを設計判断として持てます。サブスク利用者、特にClaude Codeを一日中開いたままにする使い方では、TTLは既定のまま動いていることが大半です。効いてくるのは、セッション中に何をするとキャッシュが壊れるかを知っているかどうかです。同じ「プロンプトキャッシュ」という言葉を見たときに、自分がどちらの最適化をすべきかを取り違えると、API向けの助言(TTLを自分で選ぶ)をサブスクの日常利用に持ち込んで空回りしたり、逆にサブスクの助言(操作を避ける)をAPI実装に持ち込んで単価設計を怠ったりします。

まとめ

プロンプトキャッシュの仕組み自体は、書き込み・読み取り・TTLという3つの変数に尽きます。APIキーで直接叩くなら、この3つは自分でコードに書く設計対象であり、節約は単価に直結します。Claude Codeやclaude.aiをサブスクリプションで日常的に使い続けるなら、3つのうちTTLだけが既定で1時間に伸び、節約は5時間枠・週次上限の消費速度として現れます。境界を分けるのはプラン枠の内か外かで、外に出た瞬間にAPIと同じ5分TTL・同じ単価構造に合流します。自分がいまどちらの側にいるかは、API利用者ならレスポンスのusageフィールド、Claude Code利用者なら/usageのPrompt cache (main)行で確認できます。