著者 Claude prompt cachingの損益分岐点を計算する方法
Claudeのprompt cachingはcache writeが1.25倍、cache readが0.1倍です。5 minuteは2回目、1 hourは3回目から得になります。APIで計算を検証します。
キャッシュ保存が効果を生む前にかかるコスト
Prompt caching を使うと、Claude はプロンプトの先頭部分を毎回読み直さずに再利用できます。判断の基準は、モデルの基本入力料金に対する2つの倍率です。2026年8月時点では、cache write の料金は、5 minute の有効期間では基本入力料金の1.25倍、1 hour の有効期間では2倍です。cache read の料金は0.1倍です。これらの倍率はモデル一覧全体で共通のため、トークン単価が変わっても以下の損益分岐点は変わりません。
現在の追加料金と、後続の割引を比較する仕組みです。prefix を保存する際に、最初の1回だけ追加料金を支払います。その後、まったく同じバイト列で始まるリクエストでは、その部分の入力料金が通常の10分の1になります。有効期間内に一度も再利用されない prefix は、何も得られないまま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 回の読み取りが必要です。そのため、デフォルトの選択肢にはなっていません。
以下のグラフは、20,000 トークンのプレフィックスを Claude Opus 5 で使用した場合のコストを示しています。2026 年 8 月時点での基本入力料金は、1 million tokens あたり $5 です。1 million あたり $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 token のプレフィックスを含む 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 minute cache で hit rate が90 percentの場合に、一般的な4つの構成を1,000 requestsで比較しています。
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 token のシンプルな system prompt では、キャッシュを使わない場合の $10.00 に対して、1,000 requests あたり $7.85 を節約できます。大量に処理すれば実際のコスト差になりますが、これだけで caching が興味深いわけではありません。tool definitions を追加すると、8,000 tokens になり、$31.40 を節約できます。すべてのリクエストで質問対象になる 25,000 token の policy document では、$98.12 を節約できます。最後の行は、アーキテクチャを変える規模です。120,000 tokens の codebase または transcript context は、キャッシュを使わない場合に $600.00、キャッシュを使う場合に $129.00 かかり、$471.00 を節約できます。
節約額は prefix size と hit rate に比例します。それ以外の要因には左右されません。このため、そもそも prompt に何を含める価値があるかも変わります。Claude の tokens が1 million 個ある場合の実際のコストは、2回以上送信する内容であれば、表示価格の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 エージェントの請求額を管理するための、より広い運用上の習慣と併用するものです。
キャッシュが機能していることを確認する方法
設計を信用するだけでは不十分です。レスポンスの usage ブロックを確認してください。すべての 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 回目の呼び出しでは小さい値になり、通常は新しい user message だけが対象です。Claude API には無料枠がないため、どちらの呼び出しにも料金が発生します。ただし、上記の 20,000 token のプレフィックスでは、2 回分の料金は約 14 セントです。
保存済みのリクエストボディを 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 つのルールが導かれます。呼び出しごとに変わるものは、変わらないものより後ろに置く必要があります。
典型的な原因は timestamp です。system prompt の先頭に Current time: 2026-08-03T14:07:11Z を含む行があると、ヒット率は 0 percent になります。呼び出しごとにプレフィックスのハッシュが変わるため、以前のエントリが一致することはありません。これを 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 token のシステムプロンプトは一方ではキャッシュされますが、もう一方では通知なく無視されます。
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 が発生し、再びヒットします。リクエスト間隔が lifetime を超えています。write を受け入れるか、ヒット率が 53 percent を超えることを確認したうえで 1 hour TTL に切り替えてください。
deploy 後にヒット率が低下する。 tool description を編集したか、model を変更しています。どちらの場合も prefix 全体が無効になります。prompt に影響する deploy のたびに、コストの高い write が 1 回発生すると考えてください。
caching を有効にした後、請求額が増えた。 ヒット率が損益分岐点を下回っています。5 minute cache では約 22 percent 未満の場合、prefix をキャッシュせずに送信したほうが安価です。1 hour cache では約 53 percent 未満の場合も同様です。
FAQ
プロンプトをキャッシュするメリットが得られるのは、何回再利用した場合ですか？
5 minute cache なら、1 回で元が取れます。書き込みには基本入力の 1.25x、読み取りには 0.1x がかかるため、キャッシュを使わない N 回のリクエストは N、キャッシュを使う N 回のリクエストは 1.25 + 0.1 × (N - 1) です。両者が交差するのは N = 1.28 なので、2 回目のリクエストからすでに有利です。1 hour cache は書き込みが 2x で、N = 2.11 で交差するため、2 回読み取る必要があります。
cache_read_input_tokens が常に 0 なのはなぜですか？
まず、プレフィックスの長さを確認します。モデルの最小長未満の場合、2026 年 8 月時点では Claude Opus 5 が 512 tokens、Claude Haiku 4.5 が 4,096 tokens 未満だと、キャッシュは通知なくスキップされ、両方のカウンターが 0 になります。プレフィックスが十分に長い場合は、システムプロンプト内の timestamp や session identifier など、呼び出し間で変化する内容が breakpoint 以前にないか確認します。カウンターが動作していたのに 0 になった場合は、リクエスト間隔が cache lifetime を超えています。
prompt caching によって Claude の回答は変わりますか？
いいえ。キャッシュには、すでに送信した tokens の処理済み形式が保存され、どちらの場合もモデルが受け取る prompt は同じです。これは課金とレイテンシーの機能であり、動作を変更するものではありません。そのため、動作確認済みの prompt に対して、評価を再実行せずに有効化できます。
1 hour cache に料金を支払うべきですか？
トラフィックに 5 分を超える間隔があり、hit rate が約 53 percent を引き続き上回る場合だけ利用します。ヒットしなかった場合、2x の書き込みコストは 1.25x の書き込みコストの 2 倍の負担になります。5 minute entry はヒットするたびに更新されるため、トラフィックが安定していれば、より長い lifetime の料金を支払わずに読み取り料金だけで維持できます。