Claudeのキャッシュ時間は5分か1時間か — 1時間キャッシュの使いどころ

5分キャッシュが切れる場面と、1時間にする損益分岐

Claude APIのキャッシュ時間(TTL)は、既定の5分と、"ttl": "1h"で指定する1時間の2種類です。次の呼び出しが5分を超えて届く使い方では、1時間キャッシュは2回目のリクエストから5分キャッシュより安く、3回目からはキャッシュなしより安くなります。

Claude APIのプロンプトキャッシュの既定の寿命は5分で、使われるたびに無料で延びます。この5分は、リクエストの開始時点から数えます。応答が終わった時点からではありません。応答の生成に4分かかれば、同じプレフィックスを使う次のリクエストは、応答完了からおよそ1分以内に始める必要があります。

1時間キャッシュは、この寿命を1時間にするオプションです。使えるのは、Claude API本体、Amazon Bedrock(現行版とレガシー版の両方)、Claude Platform on AWS、Google Cloud、Microsoft Foundryです。Claude Codeのサブスクでは1時間が既定になる場面があります。その切り替わり方はClaudeのプロンプトキャッシュの仕組みにあります。ここではAPIで自分でTTLを選ぶ側を扱います。

書き込みが割高になる代わりに、読み取りの単価は変わりません。問題は、その割高な書き込みを何回の再利用で取り返せるかです。

何回使えば1時間のほうが安くなるか

単価の倍率は3つです。5分キャッシュの書き込みが1.25倍、1時間キャッシュの書き込みが2倍、読み取りが標準で0.1倍(いずれもベース入力単価に対する倍率)。次の表は、リクエスト間隔がすべて5分を超え、かつ全リクエストが最初の書き込みから1時間以内に収まる場合の、プレフィックス部分の合計コストです。値はベース入力単価を1としています。

5分キャッシュは、間隔が5分を超えるたびに期限切れで書き直しになるので、毎回1.25倍の書き込みを払い続けます。キャッシュなしより高くつく点に注意が要ります。1時間キャッシュが5分キャッシュより安くなるのは2回目からで、キャッシュなしより安くなるのは3回目からです。2回で終わる使い方なら、キャッシュなしとほぼ同額です。

読み取りが0.025倍のClaude Fable 5.1(Claude Mythos 5.1も同じ)、0.05倍のClaude Opus 5.5では、回数が増えたときの差がさらに開きます。倍率はFable 5.1の記事にあるとおりモデルごとに違うため、自分のモデルの行で確かめてから計算します。

逆に、1時間にする意味が薄いのは次の場合です。

• 同じプレフィックスを5分以内の間隔で使い続ける。5分キャッシュが無料で延び続けるので、2倍の書き込みは払い損になります
• 再利用が1回しか来ない、または来るか分からない。1回目の書き込みが2倍になるだけです
• 頻繁に変わる小さな部分まで1時間TTLに含めている。書き換わるたびに割高な書き込みが走ります

自分の使い方に1時間が要るかを見極める

判断の材料は、同じプレフィックスを使う次のリクエストまでの時間分布です。手元のログから取れる順に並べると、次のようになります。

5分キャッシュと1時間キャッシュは、レイテンシーの挙動自体は同じです。長いドキュメントでは、どちらも初回トークンまでの時間が短くなります。違いは寿命とコストだけなので、応答の速さを理由に1時間を選ぶのは、フォローアップが5分を超えて届く場合に限られます。

サーバーツールの結果が5分TTLで自動キャッシュされる仕組みは、ここで選ぶTTLとは別の話です。web検索などを使っていて、意図していない5分の書き込みが見えたときは、そちらを確認します。

1時間キャッシュの指定方法と、usageでの見え方

cache_controlにttlを足します。指定できる値は"5m"(既定)と"1h"です。

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

トップレベルにcache_controlを置く自動キャッシュでも同じ指定が使えます。自動キャッシュの既定は5分で、1時間にするときは書き込みが2倍になります。最後のブロックに、TTLの違う明示的なcache_controlがあるとAPIは400を返します。TTLが同じなら何も起きません。レガシー版のAmazon Bedrock(Opus 4.6以前向け)は自動キャッシュに対応せず、トップレベルのcache_controlが400になるため、明示的なブレークポイントを使います。

レスポンスのusageには、5分と1時間それぞれの書き込みの内訳が返ります。

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

cache_creation_input_tokensは、cache_creation内の値の合計と一致します。cache_read_input_tokensも0なのにephemeral_1h_input_tokensが0のまま(ephemeral_5m_input_tokensだけに書き込まれている)なら、指定の位置か書き方を見直します。ヒットしたリクエストでは書き込みが起きないため、1時間を正しく指定していても0になります。

5分と1時間を同じリクエストに混ぜる

1つのリクエストに、1時間TTLと5分TTLのcache_controlを両方置けます。制約は1つで、TTLが長いエントリを、短いエントリより前に置くことです。1時間のブロックは、5分のブロックより先に来なければなりません。

課金は、次の3つの位置で決まります。

1. 位置A: 最も後方のキャッシュヒットまでのトークン数(ヒットが無ければ0)
2. 位置B: Aより後ろにある、最も後方の1時間cache_controlまでのトークン数(無ければAと同じ)
3. 位置C: 最後のcache_controlまでのトークン数

Aが最も後方のヒットである以上、BやCがAより大きい部分は必ずキャッシュミスです。Aまでが読み取り、(B − A)が1時間の書き込み、(C − B)が5分の書き込みとして課金されます。

ツール定義(5,000トークン)と、システムプロンプト(3,000トークン)を1時間TTL、当日のコンテキスト(2,000トークン)を5分TTLで区切った構成で追ってみます。

• ふだんは、ツール定義とシステムプロンプトの8,000トークンがヒットして位置Aが8,000になります。位置Bも8,000で、位置Cは10,000です。課金は、8,000トークンの読み取りと、2,000トークンの5分書き込みです。1時間の書き込みは0です
• システムプロンプトを書き換えた直後は、ツール定義より後ろが外れ、ヒットはツール定義の5,000トークンまでです。位置Aが5,000、位置Bが8,000、位置Cが10,000なので、3,000トークンが1時間の書き込みに、2,000トークンが5分の書き込みになります
• ツール定義まで変えると、ヒットが無くなって位置Aが0になります。8,000トークンが1時間の書き込み、2,000トークンが5分の書き込みです

上に置いた部分ほど、書き込みが起きる頻度は低く、起きたときの単価は高くなります。滅多に変わらない部分を1時間、日々変わる部分を5分で後ろに置く構成が素直に収まります。

バッチ処理で1時間キャッシュが効く理由

バッチリクエストは、処理の順序も並行度も保証されないので、キャッシュのヒットはベストエフォートです。さらに、バッチの完了には5分から1時間かかるのが一般的で、5分キャッシュでは途中で切れがちです。共通のプレフィックスを持つ大量のリクエストは、1時間キャッシュに先に書き込んでから流すと、ヒットを取りやすくなります。

バッチの割引などほかの課金修飾とは重ねて適用されます。バッチ自体の使い方はClaude Batch APIの使い方にあります。

1時間キャッシュを設定したのにヒットしないとき

疑う順序は、TTLの並び順、最小トークン数、リクエスト間の一致、ワークスペースの分離、の4つです。

TTLの並び順。1時間のブロックは、5分のブロックより前に置く必要があります。並びが逆になっていないかを確認します。

最小トークン数。1時間キャッシュでも、キャッシュできる最小のプロンプト長は5分と同じです。Claude API・Claude Platform on AWS・Google Cloud・Microsoft Foundryでは、次のとおりです。Bedrockは、モデルごとの最小値がAWS側のドキュメントで決まります。

これを下回る部分は、cache_controlを付けてもキャッシュされず、エラーも返りません。cache_creation_input_tokensとcache_read_input_tokensが両方とも0なら、キャッシュされていません。最小値に少し届かないなら、キャッシュ対象を増やして届かせるほうが、読み取り単価の安さで結果的にコストが下がる場合があります。

リクエスト間の一致。tool_choice、画像の有無、thinking設定、output_config.effortがリクエスト間で揃っているかを見ます。どれかが変わると、キャッシュの階層(tools→system→messages)のどこかが無効になり、TTLの長さに関係なくミスします。ブレークポイントまでの内容も、1文字違えばそこから後ろはキャッシュされません。並列に送るときは、最初の応答が始まってからキャッシュが使えるようになるので、1件目の応答を待ってから残りを送ります。

ワークスペースの分離。異なる組織のあいだで、キャッシュが共有されることはありません。Claude API・Claude Platform on AWS・Microsoft Foundryでは、同じ組織でもワークスペースごとに分離されます。1時間で長く保持したキャッシュも、別のワークスペースのリクエストには見えません。BedrockとGoogle Cloudは、組織単位の分離だけです。

まとめ

1時間キャッシュは、再利用の間隔が5分を超え、かつ1時間以内に2回目以降が来る使い方で効きます。1回で終わる処理や、5分以内に回り続ける処理では、5分のままのほうが安くなります。