Prompt caching には 5 分と 1 時間の 2 つの TTL があり、書き込み料金が違う。どちらを選ぶか、何リクエストで元が取れるか、そしてモデルごとに異なる「キャッシュできる最小トークン数」を整理する。キャッシュが効かないときの原因の潰し方まで、API 利用時のコスト最適化ガイドとしてまとめた。
2 つの TTL と料金倍率
キャッシュは基本入力料金に対する倍率で課金される。
| 操作 | 倍率 | |---|---| | 書き込み（5 分 TTL） | 1.25 倍 | | 書き込み（1 時間 TTL） | 2 倍 | | 読み出し（両 TTL 共通） | 0.1 倍（例外あり） |
書き込みの倍率は全モデル共通だが、読み出しは一部のモデルで安くなっている。Opus 5.5 は 0.05 倍、Fable 5.1（と限定提供の Mythos 5.1）は 0.025 倍で、それ以外は 0.1 倍。これらの倍率は、Batch API の割引やデータレジデンシーなど、ほかの料金調整と掛け合わさる。
5 分 TTL が既定で、TTL の指定は要らない。1 時間 TTL は明示的に指定する。
{
"cache_control": { "type": "ephemeral", "ttl": "1h" }
}Claude Code の既定モデルでもある Opus 5.5（入力 $4/MTok）で具体的に見るとこうなる。5 分書き込みが $5、1 時間書き込みが $8、読み出しはどちらも $0.20。
損益分岐点は TTL で違う
**1 時間 TTL は「長く効くから常にお得」ではない**。書き込みが 2 倍なので、キャッシュなしと比べて元を取るのに必要な読み出し回数が増える。
読み出しが 0.1 倍のモデルで計算すると、5 分 TTL は 2 リクエストで分岐点を越える（1.25 + 0.1 = 1.35 倍 対 キャッシュなし 2 倍）。1 時間 TTL は 3 リクエスト必要になる（2 + 0.2 = 2.2 倍 対 3 倍）。
読み出しが安い Opus 5.5 や Fable 5.1 でも、この回数は変わらない。たとえば Opus 5.5 の 1 時間 TTL を 2 リクエストで使うと 2 + 0.05 = 2.05 倍で、キャッシュなしの 2 倍をわずかに上回る。書き込みの重さが分岐点を決めているからだ。
ただしこれは「キャッシュなし」と比べた場合の話だ。あなたの呼び出し間隔は 5 分を切っているだろうか。間隔が 5 分を超える場面では、5 分 TTL は毎回失効して書き直し（1.25 倍）になる。すると 2 リクエストの時点で、5 分 TTL の 2.5 倍に対して 1 時間 TTL は 2.1 倍と、1 時間 TTL のほうが安くなる。ただし 2 リクエストだけならキャッシュなし（2 倍）がまだ最安で、1 時間 TTL がキャッシュなしを下回るのは前述のとおり 3 リクエスト目からだ。
金額にすると差がつかみやすい。Opus 5.5 で 5 万トークンの共通プレフィックスを使う場合、5 分以内に 10 回呼ぶなら、キャッシュなしは入力だけで $2.00、5 分 TTL なら書き込み $0.25 と読み出し 9 回 $0.09 で $0.34 になる。10 分間隔で 3 回呼ぶなら、キャッシュなし $0.60、毎回失効する 5 分 TTL は $0.75、1 時間 TTL は書き込み $0.40 と読み出し 2 回で $0.42 だ。
ここから使い分けが決まる。5 分より短い間隔で同じプレフィックスを叩くなら 5 分 TTL（読み出されるたびに追加料金なしで寿命が延びる）。間隔が 5 分を超えるが 1 時間以内に収まり、その間に合計 3 回以上叩く見込みがある場合や、エージェント的なタスクで 1 回の処理が 5 分を超える場合に 1 時間 TTL。寿命はレスポンスの終了ではなくリクエストの開始から数えるので、生成に時間がかかるほど寿命を消費する点も覚えておきたい。なおキャッシュヒットはレートリミットの消費に数えられないので、コスト以外の利点もある。
Claude Code を使っている場合は、TTL を自分で書く場面は少ない。Claude のサブスクリプションでプランの利用枠内なら、Claude Code はメインの会話に 1 時間 TTL を使い、使用クレジットでの課金に移ると 5 分 TTL に切り替える。API キーやクラウドプロバイダ経由では 5 分が既定で、メインの会話を 1 時間にしたければ設定の `promptCacheTtl` を `1h` にする（v2.1.242 以降）。
モデルによって最小キャッシュ長が違う（しかも単調ではない）
Claude API などでは、プレフィックスが一定のトークン数に満たないとキャッシュは作られず、エラーも出ない。
| モデル | 最小トークン数 | |---|---| | Fable 5.1 / Opus 5.5 / Sonnet 5.5 / Opus 5 / Fable 5 | 512 | | Opus 4.8 / Sonnet 5 / Sonnet 4.6 / Sonnet 4.5 | 1,024 | | Opus 4.7 / Haiku 3.5（退役済み。Bedrock・Google Cloud のみ） | 2,048 | | Opus 4.6 / Opus 4.5 / Haiku 4.5 | 4,096 |
この表は Claude API、Claude Platform on AWS、Google Cloud、Microsoft Foundry での値だ。Amazon Bedrock の値は AWS 側のドキュメントを参照する。
世代が新しいほど小さい、という単調な関係にはなっていない。Haiku は 3.5 の 2,048 に対し、新しい 4.5 のほうが 4,096 と大きい。系列をまたぐと差はさらに開き、3,000 トークンのプロンプトは Opus 5.5 や Sonnet 5 ではキャッシュされるが、Haiku 4.5 では黙って素通りする。モデルを切り替えた直後のキャッシュミスは避けられない。Claude Code のドキュメントも、キャッシュはモデルごとに別で、切り替えると同じ内容でも全体を読み直すと説明している。モデルを変えたあともキャッシュヒット率が戻らないなら、まずここを疑う。
最小長は Opus 5 で 1,024 から 512 に下がり、Opus 5.5 と Fable 5.1 も 512 になっている。Sonnet も同じで、Sonnet 5 の 1,024 に対し Sonnet 5.5 は 512 だ。Opus 4.8 以前から移ってきたなら、「短すぎてキャッシュできない」と諦めたプロンプトが、プロンプトを変えなくても、モデルを切り替えるだけで対象になる可能性がある。
キャッシュはプレフィックス一致
キャッシュキーはブレークポイントまでのプロンプト全体のハッシュから作られる。途中が少しでも変われば、それ以降のブレークポイントはすべて無効になる。
レンダリング順は tools → system → messages。安定した内容を前に、揺れる内容を後ろに置くのが原則になる。
プレフィックスが気づかないうちに変わってしまう例としては、次のようなものがある。
- system プロンプトに現在時刻やリクエスト ID を埋め込んでいる
- tool_use ブロックの JSON をキー順を固定せずにシリアライズしている（Swift や Go など、変換時にキー順がランダムになる言語がある）
- ユーザー ID を system プロンプトに差し込んでいる（プレフィックスがユーザーごとに変わり、共通部分を使い回せなくなる）
- リクエストごとにツール定義の集合が変わる
ツール定義の変更はキャッシュを全部飛ばす。一方で `tool_choice` の切り替えは、メッセージ部分のキャッシュは無効になるが、tools + system のキャッシュは保たれる（なお Opus 5.5、Fable 5.1、Sonnet 5.5 では、ツールの強制指定自体がエラーになる）。画像の追加や削除も、メッセージ部分のキャッシュを無効にする。
thinking の設定や effort の変更は扱いが違う。メッセージ部分のキャッシュは必ず無効になり、モデルによっては tools と system のキャッシュも無効になる。ただし effort をそのモデルの既定値と同じ値に明示しても、省略したのと同じ扱いで無効にはならない。
実践: ブレークポイントの置き場所（NG / OK）
公式ドキュメントが「よくある間違い」として挙げている例がわかりやすい。大きな静的コンテキスト（ブロック 1〜5）のあとに、タイムスタンプとユーザーのメッセージを含むブロック 6 が続く構成を考える。
NG は、毎回変わるブロック 6 に `cache_control` を置くことだ。タイムスタンプが毎回違うのでブロック 6 のハッシュは毎回変わり、書き込みはブロック 6 にしか起きていないので、遡って探しても使えるエントリが見つからない。結果として、毎回書き込み料金を払うのに読み出しは一度も起きない。
無料でアカウント作成
CCHub は Claude Code 開発者のための日本語コミュニティです。