著者 ClaudeのPrompt cachingは何回で元が取れる？
ClaudeのPrompt cachingは2回目から5分キャッシュが得になります。cache writeは1.25倍、cache readは0.1倍です。1時間キャッシュの損益分岐点もAPIで検証します。
キャッシュが有効になる前にかかるコスト
Prompt caching を使うと、Claude はプロンプトの先頭部分をリクエストごとに再読み込みせず、再利用できます。判断の基準は、モデルの基本入力料金に対する2つの倍率です。2026年8月時点では、cache write の料金は、5分間の有効期間では基本入力料金の1.25倍、1時間の有効期間では2倍です。cache read の料金は0.1倍です。これらの倍率はモデル一覧全体で共通です。そのため、トークン単価が変わっても、損益分岐点は変わりません。
今すぐ追加料金を支払い、後で割引を受ける仕組みです。プレフィックスを保存する際に、1回だけ追加料金がかかります。その後、まったく同じバイト列で始まるリクエストでは、その部分の入力料金が通常の10分の1になります。有効期間内に一度も再利用されないプレフィックスでは、25パーセントの追加料金だけが発生します。
損益分岐点を代数式1行で示す
キャッシュなしでプレフィックスを送信した場合の基本入力コストを B とします。キャッシュなしでは、N 回のリクエストに N × B のコストがかかります。5 分間のキャッシュでは、最初のリクエストが 1.25B でプレフィックスを書き込み、残りの N − 1 回のリクエストが 0.1B で読み取ります。両者を等しくすると、0.9N = 1.15 となり、N = 1.28 が得られます。2 回目のリクエストの時点で、キャッシュをまったく使わない場合よりすでに安くなります。
1 時間キャッシュの書き込みコストが 2 倍になる場合も同様に計算すると、0.9N = 1.9 となり、N = 2.11 です。長いキャッシュでは、損益分岐点に達するまでに 2 回の読み取りが必要です。そのため、デフォルトの選択肢にはなりません。
以下のグラフは、Claude Opus 5 で 20,000 トークンのプレフィックスを使用した場合のコストを示しています。2026 年 8 月時点で、基本入力料金は 100 万トークンあたり $5 です。100 万トークンあたり $3 のモデルでは、すべての数値を 0.6 倍してください。曲線の形状は変わりません。
The data behind this chart
[
{
"requests": 1,
"uncached_usd": "0.10",
"cached_5m_usd": "0.125",
"cached_1h_usd": "0.20"
},
{
"requests": 2,
"uncached_usd": "0.20",
"cached_5m_usd": "0.135",
"cached_1h_usd": "0.21"
},
{
"requests": 3,
"uncached_usd": "0.30",
"cached_5m_usd": "0.145",
"cached_1h_usd": "0.22"
},
{
"requests": 5,
"uncached_usd": "0.50",
"cached_5m_usd": "0.165",
"cached_1h_usd": "0.24"
},
{
"requests": 10,
"uncached_usd": "1.00",
"cached_5m_usd": "0.215",
"cached_1h_usd": "0.29"
},
{
"requests": 20,
"uncached_usd": "2.00",
"cached_5m_usd": "0.315",
"cached_1h_usd": "0.39"
}
]1 回だけのリクエストでは、キャッシュなしのコストが $0.10、キャッシュありのコストが $0.125 です。そのため、1 回しか使わないプロンプトをキャッシュすると、純粋な損失になります。2 回目のリクエストでは、5 分間キャッシュのコストは $0.135 で、キャッシュなしの $0.20 を下回ります。1 時間キャッシュはこの時点でも $0.21 で、同じ $0.20 を上回っています。3 回目のリクエストで初めてキャッシュなしのコストを下回り、$0.22 対 $0.30 になります。20 回のリクエストでは、差額は $2.00 対 $0.315 です。
キャッシュヒットでもエントリが更新されるため、公開されている料金表では、その列を cache hits and refreshes と表記しています。そのため、リクエストの多いエンドポイントでは、読み取り料金だけで 5 分間のエントリが無期限に維持されます。一方、1 時間の有効期間で 2 倍の書き込み料金を支払う価値があるのは、トラフィックに実際の間隔がある場合だけです。
ヒット率が低い場合のコスト
実際のトラフィックでは、キャッシュミスが発生します。キャッシュミスであってもブレークポイントを含むリクエストは書き込みとして課金されるため、コストはヒット率の関数としてモデル化するのが適切です。以下のグラフは、同じ 20,000 トークンのプレフィックスを含む 1,000 件のリクエストを対象にしています。
The data behind this chart
[
{
"hit_rate_percent": 0,
"cost_5m_usd": "125.00",
"cost_1h_usd": "200.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 25,
"cost_5m_usd": "96.25",
"cost_1h_usd": "152.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 50,
"cost_5m_usd": "67.50",
"cost_1h_usd": "105.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 75,
"cost_5m_usd": "38.75",
"cost_1h_usd": "57.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 90,
"cost_5m_usd": "21.50",
"cost_1h_usd": "29.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 95,
"cost_5m_usd": "15.75",
"cost_1h_usd": "19.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 99,
"cost_5m_usd": "11.15",
"cost_1h_usd": "11.90",
"uncached_usd": "100.00"
}
]ヒット率が 0 パーセントの場合、$125.00 が課金されます。これは $100.00 より高く、1 hour キャッシュでは請求額が 2 倍の $200.00 になります。1.25 - 1.15h = 1 を解くと、5 minute キャッシュがコスト削減になるヒット率は約 22 パーセントからです。そのため、25 パーセントでもすでに $96.25 になります。2 倍の書き込みコストについて同じ計算をすると、1 hour キャッシュが有利になるヒット率は約 53 パーセントです。そのため、ヒット率が 50 パーセントでも $105.00 となり、キャッシュを使わない場合のラインを上回ります。90 パーセントでは、それぞれ $21.50 と $29.00 になります。99 パーセントでは、短いキャッシュ期間のキャッシュが $11.15 に達し、キャッシュを使わない場合の料金の 10 分の 1 という下限に近づきます。
プレフィックスのサイズを固定した後に制御できる入力はヒット率だけなので、計測すべき指標はヒット率です。
ブレークポイントを設定する価値があるプレフィックス
1 回のリクエストには、キャッシュのブレークポイントを最大 4 個設定できます。では、どのブロックに設定すべきでしょうか。候補になるのは、リクエスト間でバイト単位に完全一致し、かつ無視できない大きさのブロックです。以下のグラフは、5 分間のキャッシュでヒット率 90 パーセントの場合に、一般的な 4 つの構成を 1,000 リクエスト分のコストで比較したものです。
The data behind this chart
[
{
"label": "System prompt",
"prefix_size_tokens": "2,000",
"uncached_usd": "10.00",
"cached_usd": "2.15",
"saved_usd": "7.85"
},
{
"label": "System plus tools",
"prefix_size_tokens": "8,000",
"uncached_usd": "40.00",
"cached_usd": "8.60",
"saved_usd": "31.40"
},
{
"label": "Policy document",
"prefix_size_tokens": "25,000",
"uncached_usd": "125.00",
"cached_usd": "26.88",
"saved_usd": "98.12"
},
{
"label": "Codebase context",
"prefix_size_tokens": "120,000",
"uncached_usd": "600.00",
"cached_usd": "129.00",
"saved_usd": "471.00"
}
]2,000 トークンのシンプルなシステムプロンプトでは、キャッシュを使わない場合の $10.00 に対して、1,000 リクエストあたり $7.85 を削減できます。大量利用では実際のコスト差になりますが、これだけではキャッシュの面白さは分かりません。ツール定義を追加すると 8,000 トークンになり、削減額は $31.40 です。すべてのリクエストで質問の対象になる 25,000 トークンのポリシードキュメントでは、$98.12 を削減できます。アーキテクチャを変えるのは最後の行です。コードベースまたは会話履歴のコンテキスト 120,000 トークンは、キャッシュを使わない場合に $600.00、キャッシュを使う場合に $129.00 かかり、$471.00 を削減できます。
削減額は、プレフィックスのサイズとヒット率に比例します。それ以外の要因には左右されません。このため、そもそもプロンプトに何を含める価値があるかも変わります。1 回を超えて送信する内容では、Claude の 100 万トークンに実際にかかるコストが表示価格の 10 分の 1 になります。
月額請求での見え方
以下のグラフでは、上記の 8,000 トークンのプレフィックスに、システムプロンプトとツール定義を加え、90 パーセントのヒット率で月間リクエスト数に換算しています。
The data behind this chart
[
{
"label": "10k requests",
"uncached_usd": "400.00",
"cached_usd": "86.00",
"saved_usd": "314.00"
},
{
"label": "100k requests",
"uncached_usd": "4,000.00",
"cached_usd": "860.00",
"saved_usd": "3,140.00"
},
{
"label": "1M requests",
"uncached_usd": "40,000.00",
"cached_usd": "8,600.00",
"saved_usd": "31,400.00"
}
]月間 10,000 リクエストの場合、節約額は $314.00 です。これは $400.00 と $86.00 の差額です。100,000 リクエストでは $3,140.00 になります。100 万リクエストの場合、キャッシュを使用しない入力料金は $40,000.00 で、キャッシュによりそのうち $31,400.00 を削減できます。ここで示しているのは入力トークンのみです。出力は別途課金され、キャッシュによる削減効果はありません。したがって、請求額を 90 パーセント削減できると誰かに約束する前に、この点を確認しておく必要があります。キャッシュは、VPS 上で AI エージェントの請求額を管理するための幅広い運用習慣と併用するものです。
キャッシュが機能していることを確認する方法
設計を信用するだけでは不十分です。レスポンスの使用量ブロックを確認してください。すべての Messages API (application programming interface) の応答には、書き込んだキャッシュ済みトークン数、読み取ったキャッシュ済みトークン数、処理が必要だった新規トークン数が記録されます。
from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
model="claude-opus-5",
max_tokens=512,
system=[
{
"type": "text",
"text": POLICY_DOCUMENT,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": question}],
)
u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)同じドキュメントと異なる質問で、2 回実行してください。1 回目は cache_creation_input_tokens が 0 より大きく、cache_read_input_tokens は 0 になります。2 回目はその逆になります。プレフィックスが見つかったためです。input_tokens は最後のブレークポイントより後のトークンだけを数えます。そのため、正常な 2 回目の呼び出しでは小さい値になり、通常は新しいユーザーメッセージ分だけです。
request.json に保存したリクエスト本文に対して、shell から同じ確認を行う場合は次のようにします。
curl -s 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 @request.json | jq '.usage'正常な 2 回目の呼び出しでは、次のような出力が表示されます。
{
"input_tokens": 42,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 20143,
"output_tokens": 187
}真実を示すのは 1 行です。呼び出しを繰り返しても cache_read_input_tokens が 0 のままなら、毎回 1.25x の書き込みコストを支払っているだけで、キャッシュから何も取得できていません。
有効期間が 1 hour の場合、ブレークポイントには time to live (TTL) が設定されます。
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}自動キャッシュも利用できます。リクエストのトップレベルに cache_control フィールドを 1 つ指定すると、API が会話の拡大に合わせてブレークポイントを管理します。この設定は 4 つあるブレークポイントスロットの 1 つを使用します。まずはこれを使用してください。境界を正確に決める必要がある場合は、明示的なブレークポイントに切り替えます。
ヒット率を低下させる順序規則
キャッシュはリクエストの先頭から、バイト単位で完全一致するプレフィックスを照合します。リクエストは、tools、system、messages の固定順序で組み立てられます。どのレベルでも変更すると、そのレベルと後続のすべてが無効になります。1 つのツールの説明、system prompt、メッセージ履歴のいずれかを編集すると、他の部分に変更がなくても、それ以降の全体が無効になります。
ここから、例外のないルールが 1 つ導かれます。呼び出し間で変化するものは、変化しないものより後ろに置く必要があります。
典型的な原因はタイムスタンプです。system prompt の先頭に Current time: 2026-08-03T14:07:11Z を含む行を置くと、ヒット率は 0 パーセントになります。プレフィックスのハッシュが呼び出しごとに変わるため、それより前のエントリが一致することはありません。これを user message の末尾へ移動します。セッション識別子やリクエストごとの nonce も同じようにキャッシュを壊すため、同じ方法で修正します。リクエストごとに異なる取得ドキュメントも、キャッシュされたブロックの後ろに置く必要があります。そうしないと、安定したトークンがすべて、位置の変わる境界の後ろに置かれてしまいます。
2 つ目の原因は、変更されるブロック自体にブレークポイントを置くことです。キャッシュへの書き込みはブレークポイントで行われます。そのため、そのブロックが毎回異なると、安定した内容が何も保存されません。lookback で見つかるのは、以前のリクエストがそれぞれの変動するブレークポイントに書き込んだエントリだけです。リクエスト間で内容が同一の最後のブロックに cache_control を置きます。
3 つ目は、prompt の内容だと考えていなかったパラメーターの変更です。モデルが異なれば、キャッシュも異なります。tool choice を変更すると、system レベル以降が無効になります。ツールを追加または削除すると、すべてが無効になります。
最小プレフィックスと、通知されない無操作
モデルの最小長より短いプレフィックスはキャッシュされず、そのことを知らせる表示もありません。エラーも警告も出ません。リクエストは成功しますが、両方のカウンターは 0 になります。2026 年 8 月時点で公開されている最小値は次のとおりです。
- Claude Opus 5 と Claude Fable 5 は 512 tokens
- Claude Sonnet 5 と Claude Opus 4.8 は 1,024 tokens
- Claude Haiku 4.5 は 4,096 tokens
キャッシュされているはずのリクエストで両方のカウンターが 0 になった場合は、まずプレフィックスの長さを確認してください。これが、キャッシュを使用するワークロードでは最も安価なモデルが自動的に最安になるとは限らない理由でもあります。Haiku 4.5 はキャッシュが有効になるまでに Opus 5 の 8 倍の長さのプレフィックスを必要とします。そのため、2,000 tokens のシステムプロンプトは一方ではキャッシュされますが、もう一方では通知なしに無視されます。
Claude Code がキャッシュする場所と、キャッシュで対応できない場合
Claude Code は、独自のプレフィックスをキャッシュします。システムプロンプトとツール定義はすべてのリクエストの先頭に置かれ、移動しないため、1 回だけ書き込まれ、その後のセッションでは読み戻されます。そのため、長いセッションでもターンごとのコストはコンテキストサイズから想定される値を大幅に下回ります。この動作は、Claude Code がトークン使用量を報告する方法で説明しているカウンターにも表示されます。
キャッシュで対応できないのは、コンテキストの先頭付近を編集した場合です。会話履歴は追記専用のため、通常の新しいターンでは、すでにキャッシュされたプレフィックスが拡張されます。セッションの早い段階で読み込んだファイルを編集すると、そのプレフィックスの途中にある内容が変わります。その変更以降のすべてのトークンを、再度書き込む必要があります。長いアイドル時間が発生した場合も同じです。エントリの有効期限が切れ、次のターンで全体を書き込む必要があるためです。いずれもバグではありません。どちらも、プレフィックスの規則どおりの動作です。
代わりに独自のクライアントを作成する場合は、後からレイアウトを変更するのではなく、最初のリクエストからこの構成を適用してください。VPS で最初の Claude API アプリを作成する方法と同じように、安定したブロックを先に置き、変動するブロックを最後に配置してリクエストを組み立てます。
障害パターンと確認できる内容
すべての呼び出しが write になる。 cache_creation_input_tokens はすべてのリクエストで 0 より大きく、cache_read_input_tokens は 0 のままです。ブレークポイント以前のどこかで、呼び出しごとに内容が変化しています。組み立てた prefix の先頭 200 文字を連続する 2 回のリクエストで出力し、目視で比較してください。
両方のカウンターが 0 になる。 prefix がモデルの最小長に達していないか、cache_control フィールドが API に届いていません。まず prefix のトークン数を数え、次に実際に送信したリクエストボディをログに記録してください。
読み取りが機能した後に停止する。 ヒットが連続した後に write が発生し、その後またヒットします。リクエスト間の間隔が有効期間を超えています。write を受け入れるか、ヒット率が 53 パーセントを超えていることを確認したうえで、1 hour TTL に変更してください。
デプロイ後にヒット率が低下する。 ツールの説明を編集したか、モデルを変更しています。どちらの場合も prefix 全体が無効になります。プロンプトに変更を加えるデプロイのたびに、コストの高い write が 1 回発生すると考えてください。
キャッシュを有効にした後、請求額が増えた。 ヒット率が損益分岐点を下回っています。5 minute cache では約 22 パーセント未満の場合、prefix をキャッシュせずに送信するほうが安価です。1 hour cache では約 53 パーセント未満の場合も同様です。
FAQ
プロンプトをキャッシュすると採算が合うまで、同じプロンプトを何回再利用する必要がありますか？
5 minute cache なら 1 回です。書き込みの料金は基本入力料金の 1.25 倍、読み取りは 0.1 倍です。そのため、キャッシュなしの N 回のリクエストは N の料金になり、キャッシュありでは 1.25 + 0.1 × (N - 1) になります。両者が交差するのは N = 1.28 なので、2 回目のリクエストですでに得になります。1 hour cache は書き込みが 2 倍で、N = 2.11 で交差するため、2 回の読み取りが必要です。
cache_read_input_tokens が常に 0 なのはなぜですか？
まずプレフィックスの長さを確認してください。モデルの最小長未満の場合、August 2026 時点では Claude Opus 5 が 512 tokens、Claude Haiku 4.5 が 4,096 tokens 未満の場合、キャッシュは通知なしにスキップされ、両方のカウンターが 0 になります。プレフィックスが十分に長い場合は、ブレークポイント以前またはブレークポイント上に、呼び出し間で変化する内容がないか確認してください。たとえば、system prompt 内のタイムスタンプやセッション識別子などです。カウンターが機能していたのに 0 になった場合は、リクエスト間の間隔がキャッシュの有効期間を超えています。
プロンプトキャッシュによって Claude の回答は変わりますか？
いいえ。キャッシュには、送信済みトークンを処理した形式が保存され、どちらの場合もモデルが受け取るプロンプトは同じです。これは料金とレイテンシーに関する機能であり、動作を変更するものではありません。そのため、動作確認済みのプロンプトでも、評価を再実行せずに有効化できます。
1 hour cache の料金を支払うべきですか？
トラフィックに 5 分を超える間隔があり、その場合でもヒット率が概ね 53 パーセントを超える場合に限ります。ヒットしない場合、2 倍の書き込み料金による不利は、1.25 倍の書き込み料金の場合の 2 倍です。5 minute cache のエントリはヒットするたびに更新されるため、一定のトラフィックがあれば、より長い有効期間の料金を支払わずに読み取り料金だけで維持できます。