プロンプトキャッシュとは｜効かない5つの原因と確認方法

「プロンプトキャッシュを設定したのに、請求が思ったより下がらない」「キャッシュが効いているのかどうか、そもそも確認する方法がわからない」——AIをAPIで動かし始めた方から、いちばんよく聞く困りごとです。

結論から言うと、プロンプトキャッシュが効かない原因のほとんどは「設定を入れ忘れた」ではなく「入れたのに条件を外している」です。しかも条件を外したとき、エラーは一切返りません。黙って通常料金で処理されるだけなので、気づかないまま払い続けることになります。

株式会社Fyveは中小企業のAI導入を支援していますが、この「気づけない出費」は自分たちの無人運用でも実際に踏んだ落とし穴でした。この記事では、公式ドキュメントに書かれている仕様をもとに、キャッシュが効かなくなる5つの原因と、効いているかどうかを自分で確かめる方法を整理します。

先に対象を絞ります｜この話が効くのは「API従量課金」の人だけ

最初にはっきりさせておきます。この記事の内容が請求に影響するのは、Claude APIを従量課金（使った分だけ支払う形）で使っている場合だけです。

月額プランでClaude.aiやClaude Codeを使っている方の請求額は、キャッシュが効いていても効いていなくても変わりません。定額だからです。ここを最初に切り分けないと、大半の読者にとって無関係な話になってしまいます。

ただし、月額プランの方にも無関係ではない部分があります。キャッシュが効いているかどうかは応答の速さにも関わるためです。同じ前提を読み直す処理が減れば、返ってくるまでの時間は短くなります。請求は変わらなくても、体感は変わります。

なお「結局いくらになるのか」という金額そのものの試算は、別の記事で計算例つきに整理しています。この記事は金額ではなく「なぜその額になるのか」という仕組みの側を扱います。

Claude CodeClaude Fable 5.1の料金｜月いくらかかるのか

プロンプトキャッシュとは｜同じ資料を毎回渡し直さなくて済む仕組み

プロンプトキャッシュとは、一度読ませた内容をモデル側に覚えておいてもらい、次回以降は安い単価で読み出せるようにする仕組みです。

AIに仕事をさせるとき、毎回同じものを渡している部分があります。役割の説明、社内のルール、長い仕様書、これまでのやりとりの履歴。こうした「変わらない部分」を毎回まるごと読ませ直すと、そのたびに通常の入力料金がかかります。キャッシュは、この読み直しの単価を下げるための機能です。

書き込みと読み取りで単価が分かれている

ここが最初のつまずきどころです。キャッシュの料金は1種類ではなく、作るとき（書き込み）と使うとき（読み取り）で別々に決まっています。

公式の料金ページでは、基本の入力単価に対する倍率として整理されています（2026年9月7日時点）。

つまりキャッシュは「作った瞬間は割高になる」のです。1回書き込んで一度も読まなければ、通常より1.25倍高く払って終わりです。

何回読み直せば元が取れるのか

公式ドキュメントは損益分岐点を明記しています。読み取りが標準の0.1倍の場合、5分キャッシュなら1回読めば元が取れ、1時間キャッシュなら2回読めば元が取れるという説明です。

これは実務上とても重要な線引きです。「とりあえずキャッシュを付けておけば安くなる」ではありません。同じ内容を2回以上読み直す見込みがあるかどうかが判断の分かれ目になります。1回きりの処理にキャッシュを付けると、確実に損をします。

なおモデルによって読み取りの単価は違います。Claude Fable 5.1とClaude Mythos 5.1については、料金表の脚注で基本入力単価の0.025倍という特例が明記されており、100万トークンあたり$0.25です。他のモデルは標準の0.1倍が適用されます。この2モデルでは、元が取れるまでの回数はさらに短くなります。

読者特典・無料ダウンロードClaude Codeを「素のまま」使うな無料でダウンロード →↓

原因1｜1文字でも違えば「別のもの」として扱われる

いちばん多い原因がこれです。公式ドキュメントには次のように書かれています。

Cache hits require 100% identical prompt segments, including all text and images up to and including the block marked with cache control.
（キャッシュのヒットには、キャッシュ指定を付けたブロックまでのすべてのテキストと画像を含め、完全に同一のプロンプト部分が必要です）

「だいたい同じ」では当たりません。100%同一である必要があります。

ここで起きがちな事故が、変わるものを前に置いてしまうことです。公式ドキュメントが挙げている失敗例そのものですが、たとえば「現在の日時」をキャッシュ対象のブロックに含めてしまうと、実行するたびに中身が変わります。その結果、一度もキャッシュに当たらないまま、毎回書き込み料金（1.25倍）を払い続けることになります。

私自身、毎日決まった時刻にAIへ同じ手順書を読ませて作業させる処理を動かしていますが、ここは実際に順番を組み替えた箇所です。手順書は数千行あってほぼ変わらない一方、その日の日付と当日の素材は毎回変わります。変わらないものを先に、変わるものを後に——この順番を守るだけで、読み直しの扱いはまったく変わります。

原因2｜キャッシュには階層があり、上を触ると下が全部落ちる

2つめの原因は、キャッシュが独立した1つの塊ではなく、階層構造になっていることを知らないまま設定を変えてしまうケースです。

公式ドキュメントは、キャッシュが tools（ツール定義）→ system（役割や前提の指示）→ messages（やりとりの履歴）という順序の階層に従うと説明しています。そして「各レベルでの変更は、そのレベルと、それ以降のすべてのレベルを無効にする」としています。

つまりいちばん上のツール定義を1文字変えると、その下の指示も履歴も、まとめて無効になります。公式が示している対応表を整理すると次のとおりです（✓＝そのレベルのキャッシュは残る／✘＝無効になる）。

この表で見落とされやすいのが速度設定です。応答を速くする設定を切り替えただけで、指示と履歴のキャッシュが無効になります。「モデルも指示も変えていないのに急に高くなった」というときは、ここを疑う価値があります。

もうひとつは画像です。会話の途中で画像を1枚足すと、それ以降の履歴のキャッシュが落ちます。画像を扱う処理でキャッシュが安定しないときの典型的な原因です。

原因3｜短すぎるものは、黙ってキャッシュされない

3つめが、いちばん気づきにくい原因です。一定の長さに満たないものは、キャッシュ指定を付けてもキャッシュされません。そしてエラーも警告も返りません。

公式ドキュメントの記述はこうです。

Shorter prompts cannot be cached, even if marked with cache_control. Any requests to cache fewer than this number of tokens will be processed without caching, and no error is returned.
（これより短いプロンプトは、キャッシュ指定を付けてもキャッシュできません。この数を下回るキャッシュ要求は、キャッシュなしで処理され、エラーは返りません）

この最小の長さはモデルごとに違います。しかも新しいモデルほど短い、という単純な並びにはなっていません。

並びを見てください。Opus 4.5と4.6は4,096、Opus 4.7は2,048、Opus 4.8は1,024、Opus 5は512です。世代が進むごとに条件がゆるくなっています。逆に言えば、古いモデルで動いていた設定をそのまま新しいモデルに持っていくのは安全ですが、その逆は危険ということです。

特に注意したいのがClaude Haiku 4.5です。軽くて安いモデルなので短い処理に使われがちですが、最小トークン数は4,096と全モデル中で最も長い部類です。「安いモデルでキャッシュも効かせて徹底的にコストを下げよう」という発想が、いちばん空振りしやすい組み合わせになっています。

原因4｜有効期限の起点は「返答が終わったとき」ではない

4つめは時間の数え方です。5分キャッシュの「5分」がいつから始まるのか、直感と食い違います。

The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response.
（有効期間は、キャッシュを書き込むか読み取るリクエストの開始時点から測られます。その応答が終わった時点からではありません）

公式ドキュメントはさらに具体例を挙げています。応答のストリーミングに4分かかった場合、同じキャッシュを再利用する次のリクエストは、その応答が完了してから約1分以内に開始しなければならないという説明です。

これは長時間動く処理で確実に効いてきます。AIが考えて答えを返している時間も、5分の中に含まれているからです。

私の無人運用でも、ここは実際に引っかかりました。1回の実行の中でAIを何度も呼び出すのですが、その途中に画像の生成や外部サイトの取得といった時間のかかる処理が挟まります。処理そのものは正しく動いているので、失敗としては表に出ません。ただ、間が空いた分だけキャッシュが切れて、次の呼び出しが書き込みからやり直しになっていただけです。席を外して戻ってきたときも同じで、戻ってからは「当たらない前提」で考えるのが正解です。

間隔が5分を超えることが構造的に避けられないなら、1時間キャッシュ（書き込み2倍）を選ぶ判断もあります。ただし前述のとおり、1時間キャッシュは2回以上読まないと元が取れません。

原因5｜設定やツール定義を、そのつど変えている

5つめは、原因1と原因2の合わせ技として現れるものです。試行錯誤しながら設定をこまめに変えている段階では、キャッシュは基本的に効きません。

ツールの説明文を少し直す、システム側の指示を1行足す、思考の深さの設定を変えてみる。開発中はどれもごく普通の作業ですが、そのたびにキャッシュは作り直しになります。作り直しは1.25倍の書き込み料金なので、頻繁に手を入れている間はむしろ通常より高くつきます。

ここは割り切りが要ります。キャッシュが本当に効くのは設定が固まって、同じ形で繰り返し動かす段階に入ってからです。私は、作りながら試している間はキャッシュのことを一度忘れて、動作が安定してから改めて設計し直すようにしています。

ツールを使っているなら、定義そのものが毎回の入力に乗っている

原因2で「ツール定義を変えると全部無効になる」と書きましたが、ツールを使う処理では、そもそもツールの定義自体が毎回の入力トークンに含まれている点も押さえておく必要があります。

AIに外部の操作をさせるとき、どんな道具が使えるかの説明（名前・用途・受け取る値の形）をすべて渡します。これは会話の中身とは別に、毎回積み上がります。さらに公式ドキュメントによれば、ツールを渡すとツール利用を有効にするための専用の指示文が自動で追加され、その分のトークンも加算されます。

この自動追加分はモデルと設定によって決まっており、公式に数値が公開されています（2026年9月7日時点）。

1回あたりで見れば小さな数字です。ですがツール定義は階層のいちばん上にあり、最も安定させやすい部分でもあります。裏を返せば、ここが毎回変わっている処理は、いちばん大きな塊を毎回作り直していることになります。

実務的な結論はシンプルです。ツールの一覧と説明文は、使うかどうかにかかわらず固定しておく。「この処理では使わないから外しておこう」と条件によって出し入れすると、そのたびに下の階層まで巻き添えで無効になります。使わないツールを渡しておくコストより、キャッシュが毎回壊れるコストのほうが大きくなりがちです。

効いていないときの切り分け手順

原因を5つ挙げましたが、実際に困っている場面ではどれに当たっているかを順番に絞り込むほうが早いです。上から順に確認してください。

1. そもそもAPI従量課金かを確認する。月額プランなら、ここで終わりです
2. cache_read_input_tokens と cache_creation_input_tokens を見る。両方0なら、キャッシュ自体が作られていません
3. 両方0だった場合、キャッシュ対象が最小トークン数を超えているかを確認する（原因3）。モデルによって512〜4,096と幅があります。特にHaiku 4.5は4,096です
4. 書き込みだけ増えて読み取りが0なら、キャッシュ対象の中に毎回変わるものが混ざっていないかを確認する（原因1）。日時・実行ID・乱数が典型です
5. それでも当たらないなら、呼び出しの間隔が5分を超えていないかを測る（原因4）。応答の生成時間も含まれる点に注意します
6. 間隔も問題なければ、ツール定義・速度設定・画像の追加など、階層の上を触っていないかを確認する（原因2・原因5）

この順番には理由があります。上ほど「確認が一瞬で終わり、かつ該当したら他を見る必要がない」ものから並べています。いきなり階層の話から入ると、実は最小トークン数を下回っていただけ、という結論に辿り着くまでに時間がかかります。

なお、こうした「気づかないうちに増えている支払い」を構造的に防ぐには、上限そのものを設けておく方法もあわせて検討する価値があります。

Claude CodeClaude Codeの予算上限設定｜課金事故を防ぐ実務チェック

効いているかどうかを、自分で確認する

ここまで5つの原因を挙げましたが、いちばん大切なのは「自分の場合は効いているのか」を推測ではなく数字で確かめることです。エラーが出ない以上、確認しない限り永遠に気づけません。

公式ドキュメントは確認方法を明記しています。APIの応答に含まれる使用量の項目を見て、次の2つの数字を確認します。

• cache_creation_input_tokens — キャッシュに書き込まれたトークン数
• cache_read_input_tokens — キャッシュから読み取られたトークン数

判定はシンプルです。

• 両方とも0 → キャッシュされていません。最小トークン数を下回っている可能性が高いです（原因3）
• 書き込みだけ増えて、読み取りが0のまま → 作ってはいるが一度も当たっていません。毎回1.25倍を払っている状態です（原因1・原因2・原因4のいずれか）
• 読み取りが継続的に増えている → 効いています

2番目のパターンが、いちばんたちの悪い状態です。キャッシュを設定した結果、設定しないときより高くなっているのに、動作は正常なので誰も気づきません。まずはこの2つの数字を1週間ぶん並べてみることを勧めます。

効かせるための順番と、自動キャッシュという選択肢

原因の裏返しになりますが、効かせるためにやることは3つに整理できます。

1. 変わらないものと変わるものを分ける。役割の説明・ルール・仕様書は前者、今日の日付・今回の依頼は後者です
2. 変わらないものを先に、変わるものを後に置く。順番が逆だと、後ろがどれだけ安定していても意味がありません
3. 安定するまでは設定をいじらない。ツール定義を1文字変えれば、その下は全部作り直しです

そのうえで、公式ドキュメントは手動でキャッシュの区切りを指定する方法と、自動に任せる方法の2つを用意しています。自動のほうは、リクエストの最上位に指定を1つ足すだけで、やりとりが伸びていくのに合わせて区切り位置をシステム側が管理してくれるものです。公式はこれを「ほとんどの用途で最初に試すべき出発点」と位置づけています。

区切り位置を自分で設計して外し続けるくらいなら、まず自動に任せて、前述の2つの数字で効き具合を測るほうが早いはずです。

もうひとつの落とし穴｜割引や上乗せは重なる

最後に、請求を読むときに知っておくと混乱しない点を挙げておきます。公式ドキュメントは、これらの倍率が他の価格の調整と重なって適用されると説明しています。

たとえばまとめて処理する仕組みの割引とキャッシュは、条件を満たせば両方効きます。逆に、処理する地域を限定する設定を使うと、入力・出力だけでなくキャッシュの書き込みと読み取りにも1.1倍が乗ります。

「キャッシュを効かせたのに単価の計算が合わない」というときは、こうした上乗せが重なっている可能性を見てください。単価表の1行だけを見て計算すると合いません。

Claude CodeClaude API料金ガイド【2026年版】トークン単価と節約術

よくある質問

キャッシュを設定したのにエラーが出ません。効いているということですか

いいえ。エラーが出ないことは、効いている証拠になりません。公式ドキュメントが明記しているとおり、最小トークン数を下回った場合はキャッシュなしで処理され、エラーは返らない仕様です。応答の cache_read_input_tokens を確認してください。

月額プランを使っています。キャッシュの設定は必要ですか

請求額という意味では、月額プランの支払いは変わりません。設定して直接得をするのは、API従量課金で使っている場合です。

キャッシュを付ければ必ず安くなりますか

いいえ。書き込みは通常の1.25倍（1時間キャッシュなら2倍）かかるため、一度も読み直さない処理に付けると必ず損をします。同じ内容を繰り返し読ませる見込みがあるかどうかで判断してください。

モデルを変えたらキャッシュが効かなくなりました

最小トークン数がモデルごとに違うためです。たとえばOpus 5では512トークンで足りていたものが、Haiku 4.5では4,096トークン必要になります。新しいモデルから古いモデルへ移すときは、この条件を必ず確認してください。

5分と1時間、どちらを選ぶべきですか

呼び出しの間隔で決めます。間隔が5分以内に収まるなら5分キャッシュで十分です。間に時間のかかる処理が挟まって5分を超えるなら1時間キャッシュを検討しますが、書き込みが2倍になるため2回以上読み直す前提が必要です。

単価はこの先も同じですか

この記事の数値は2026年9月7日時点で公式の料金ページに記載されている内容です。料金は改定されることがあるため、契約や請求の判断をする前に必ず最新の公式ページでご確認ください。

まとめ

プロンプトキャッシュが効かないときに見るべき点を整理します。

• 効くのはAPI従量課金の場合。月額プランの請求は変わらない
• キャッシュのヒットには完全に同一であることが必要。変わるものを前に置くと一度も当たらない
• キャッシュは tools → system → messages の階層。上を変えると下も無効になる。速度設定や画像の追加でも落ちる
• 最小トークン数はモデルごとに違う（512〜4,096）。下回ると黙ってキャッシュされず、エラーも出ない
• 有効期限の起点はリクエストの開始時点。応答を待っている時間も含まれる
• 確認は cache_creation_input_tokens と cache_read_input_tokens の2つ。書き込みだけ増えて読み取りが0なら、通常より高く払っている

この機能のいちばん厄介なところは、失敗しても何も起きないことです。処理は正常に終わり、結果も正しく返ってきます。ただ、想定より高い金額を払い続けているだけです。だからこそ、設定した時点で満足せず、数字で確認する工程まで含めて運用に組み込む必要があります。

株式会社Fyveでは、こうした「動いてはいるが、気づかないまま損をしている」箇所を洗い出すところからAI活用の支援を行っています。まずは自分の使用量の内訳を1週間ぶん並べてみるところから始めてみてください。