Claude APIの1時間キャッシュはいつ使うべきか

デフォルトの5分キャッシュでは足りない場面がある

Claude APIのプロンプトキャッシュは既定で5分の寿命を持ちます。この寿命はリクエストの開始時点から計測され、応答が終わった時点からではありません。レスポンスの生成に4分かかった場合、同じキャッシュ済みプレフィックスを再利用する次のリクエストは、その応答完了からおよそ1分以内に始める必要があります。

エージェントのサブタスクが5分を超えて続く、あるいはユーザーが次のメッセージを送るまでに5分以上の間隔が空くことが珍しくないアプリケーションでは、この5分という寿命がボトルネックになります。Anthropicはこの用途向けに、追加コストと引き換えに1時間のキャッシュ寿命を提供しています。

1時間キャッシュはClaude API本体に加えて、Amazon Bedrock(現行・Opus 4.6以前のレガシー版の両方)、Claude Platform on AWS、Google Cloud、Microsoft Foundryで利用できます。

1時間キャッシュの指定方法

cache_control 定義に ttl を追加するだけです。

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

レスポンスの 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 オブジェクト内の値の合計と一致します。web検索などのサーバーツールを使っていて、意図していない ephemeral_5m_input_tokens の書き込みが見えた場合は、サーバーツール側の自動キャッシュ挙動を確認する必要があります。

1時間キャッシュが向く場面と向かない場面

頻繁に(5分以内の間隔で)使われるプロンプトは、そのままにしていても追加コストなしで5分キャッシュが更新され続けます。この場合は5分キャッシュのままで問題ありません。

1時間キャッシュが効果を発揮するのは次のような場面です。サーバーツールの結果が5分TTLで自動キャッシュされる仕組みとは独立した、こちら側で明示的に選ぶキャッシュ寿命の話です。

5分キャッシュと1時間キャッシュはレイテンシーの挙動自体は同じで、長いドキュメントに対してはどちらも初回トークンまでの時間が改善します。違いは寿命とコストだけです。

書き込み単価は2倍、読み取り単価は変わらない

1時間キャッシュの追加コストは「書き込み」にだけ乗ります。公式の価格表(Claude Opus 5の例)は次のとおりです。

読み取り単価はTTLの長さに関係なく同じです。つまり1時間キャッシュを選ぶことで追加コストが発生するのは書き込みのタイミングだけで、その後の読み取りは5分キャッシュと同じ単価で済みます。頻繁に再利用されるプロンプトほど、2倍の書き込みコストは読み取りの回数で相殺されやすくなります。

5分と1時間を同一リクエストで混在させる

1つのリクエスト内で1時間TTLと5分TTLの cache_control を両方使うこともできます。ただし制約が1つあります。TTLが長いキャッシュエントリは、TTLが短いエントリより前に置く必要があります(1時間キャッシュのブロックは、5分キャッシュのブロックより先に来なければなりません)。

TTLを混在させた場合、APIは課金対象の位置を3つ特定します。

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

BまたはCがAより大きい場合、その部分は必ずキャッシュミスになります(Aが最も後方のヒットである以上、それより後ろは未ヒットだからです)。課金は次の3つに分かれます。

• Aまでの区間: キャッシュ読み取りトークン
• (B − A)の区間: 1時間キャッシュの書き込みトークン
• (C − B)の区間: 5分キャッシュの書き込みトークン

たとえば、ツール定義とシステムプロンプトのように滅多に変わらない部分を1時間TTLで固定し、日々更新されるコンテキスト部分を5分TTLでその後ろに置く構成なら、ツール定義とシステムプロンプトは1時間キャッシュとして安定して読み取られ続け、変動の多いコンテキスト部分だけが5分キャッシュとして頻繁に書き換わる、という役割分担ができます。

混在課金を具体的な数値で追う

位置A・B・Cの考え方を、仮の数値で追ってみます。ツール定義(5,000トークン)を1時間TTL、システムプロンプト(3,000トークン)も1時間TTL、当日のコンテキスト(2,000トークン)を5分TTLで区切っているリクエストを想定します。

• 過去のリクエストでツール定義とシステムプロンプトまでの8,000トークンが1時間キャッシュにヒットしている場合、位置Aは8,000
• 1時間TTLのブレークポイントがA以降に無いため、位置BはAと同じ8,000
• 最後のブレークポイント(5分TTL、コンテキストの末尾)が位置Cで10,000

この場合、課金は「Aまでの8,000トークンをキャッシュ読み取り」「(B−A)=0トークンなので1時間キャッシュ書き込みは発生せず」「(C−B)=2,000トークンを5分キャッシュ書き込み」に分かれます。逆に、コンテキストの内容が変わってシステムプロンプトの位置(1時間TTL)からキャッシュミスした場合は、位置Aが0まで下がり、(B−A)の8,000トークン分が1時間キャッシュの書き込み対象になります。TTLが長いブロックほど「書き込みが起きる頻度は低いが、起きたときの単価は高い」構造になっている点が、この位置A・B・Cの計算式にそのまま表れています。

導入判断のチェックリスト

1時間キャッシュを導入するかどうかは、次の3点を実測してから決めます。

• 再利用の間隔: 同じプレフィックスを使う次のリクエストまでの時間分布を取り、5分を超える割合がどれくらいあるかを見ます。ほとんどが5分以内に収まるなら1時間キャッシュの効果は薄いです
• 書き込み対象のサイズ: 1時間キャッシュにする対象が大きいほど、2倍の書き込み単価が効いてきます。頻繁に変わる小さな部分まで1時間TTLに含めると、書き換えのたびに割高な書き込みが発生します
• レート制限への影響: キャッシュヒット分はレート制限の消費に数えられないため、レート制限に余裕がない構成では1時間キャッシュで読み取り比率を上げることがレート制限対策としても働きます

最小トークン数の条件は5分キャッシュと同じ

1時間キャッシュを使う場合でも、キャッシュ可能な最小プロンプト長の条件は5分キャッシュと変わりません。この最小値はモデルとプラットフォームの組み合わせで決まっており、Claude Opus 5・Claude Fable 5・Claude Fable 5.1・Claude Mythos 5.1では512トークン、Claude Opus 4.8・Claude Sonnet 5・Claude Sonnet 4.6・Claude Sonnet 4.5では1,024トークンです。これを下回るプロンプトは cache_control を付けても課金対象にすらならず、エラーも返らないままキャッシュなしで処理されます。TTLをどちらに設定するかを検討する前に、そもそもキャッシュ対象のブロックが最小トークン数を満たしているかを、レスポンスの cache_creation_input_tokens と cache_read_input_tokens がどちらも0でないかで確認しておく必要があります。

組織・ワークスペース単位の分離は5分キャッシュと共通

1時間キャッシュも5分キャッシュも、キャッシュの分離範囲は組織・ワークスペース単位である点は変わりません。異なる組織間でキャッシュが共有されることはなく、同一プロンプトを使っていても他組織のキャッシュを読み取ることはできません。Claude API・Claude Platform on AWS・Microsoft Foundryではワークスペース単位でも分離されるため、同一組織内で複数のワークスペースを使い分けている場合は、1時間TTLで長く保持したつもりのキャッシュがワークスペースをまたいだ別のリクエストからは見えない、という設計を前提にする必要があります(Bedrock・Google Cloudは組織単位の分離のみ)。キャッシュのヒットには、テキスト・画像を含むプロンプトの該当区間がブレークポイントまで完全一致していることも条件になります。

トラブルシューティングの起点

1時間キャッシュを設定したのにヒットしない場合、まず疑うべきは「TTLの並び順」です。前述のとおり、1時間TTLのブロックは5分TTLのブロックより前に置く必要があり、この順序を守っていないとAPI側の課金位置計算が想定どおりに動きません。次に確認するのは、tool_choice や画像の有無、thinking設定、output_config.effort がリクエスト間で一致しているかどうかです。これらはどれもキャッシュの階層(tools → system → messages)のどこかを無効化する要因になり、TTLの長さに関係なくキャッシュミスを引き起こします。

最後に、混在させたブレークポイントの位置そのものが「リクエストごとに完全一致しているか」を確認します。TTLの長さは寿命を決めるだけで、一致判定の厳密さ自体は5分キャッシュと変わりません。1文字でも異なれば、そのブロック以降はキャッシュ対象から外れます。

まとめ

1時間キャッシュは「5分では短すぎるが、常時使うわけでもないプロンプト」のためのオプションです。書き込み単価がベースの2倍になる代わりに寿命が12倍になるため、再利用の間隔が5分を超える構成では総コストが下がる可能性があります。5分キャッシュと1時間キャッシュを併用する場合は、TTLの長いブロックを短いブロックより前に配置する制約を守り、変更頻度が低い部分を1時間キャッシュ、頻繁に変わる部分を5分キャッシュに振り分けるのが基本の設計です。