Anthropic APIのPrompt Cachingを理解する — コスト削減の仕組みと適用判断

要点

Prompt CachingはAnthropic APIが提供する仕組みで、長いsystem promptやdocumentコンテキストを再利用するときに大幅なコスト削減と低レイテンシを実現します。仕組みは「最初の呼び出しでキャッシュを書き込み、その後の呼び出しでキャッシュを読むだけ」というシンプルな設計ですが、適用判断を間違えると効果が出ません。

本記事は次の3点を扱います。

1. キャッシュの仕組み(なぜコストが下がるか)
2. 適用すべきシーン / すべきでないシーン
3. 実装パターン(コード例)

なぜキャッシュでコストが下がるか

通常のAPI呼び出し

普通のAPI callでは、毎回system prompt + user message + (tools定義など)を送信します。これらすべてが毎回inputトークンとして課金されます。

[Call 1] system prompt(5000 tokens)+ user(50)+ tools(2000) → 7050 input tokens
[Call 2] system prompt(5000 tokens)+ user(50)+ tools(2000) → 7050 input tokens
[Call 3] ...

10回の繰り返しで70,500 input tokens × 単価がかかります。

Prompt Cachingを使う場合

最初の呼び出しでキャッシュ書き込み(write)が走り、以降の呼び出しは キャッシュ読み込み(read)で済みます。

[Call 1] system + tools をキャッシュ書き込み → 7000 tokens(write 単価、+25%)+ user 50
[Call 2] system + tools はキャッシュ読み込み → 7000 tokens(read 単価、-90%)+ user 50
[Call 3] ...

読み込み時の単価は通常の約1/10(0.1x)、書き込み時は1.25x(初回コスト)。10回繰り返した時の総コストは、通常版の30〜40% に下がる概算です。

概算倍率(2026-05時点)

価格は時期により改定されるため、本記事は概算倍率の「相場感」のみ扱い、正確な現行料金は記事内では断定しません。判断軸の整理に集中します。

2026-05時点の概算値:Anthropic公式のPrompt Cachingドキュメントの現行表記を概算で示しています。倍率とTTLは今後変更される可能性があるため、本番投入前にsourceUrlsの公式ドキュメントで現行値を確認してください。

キャッシュTTLは5分版(短命、デフォルト)と1時間版(長命)があります。

5分版と1時間版の単価差

書き込み単価はTTLで変わります。公式ドキュメントの2026-05時点の表記では、5分版の書き込みは通常inputの約1.25x、1時間版の書き込みは約2xです。読み込み単価はどちらも約0.1xで共通です。

5分版はヒットするたびにTTLが無料でリフレッシュされるので、トラフィックが途切れずに続く限り維持されます。会話の間隔が5分を超えやすいボットや、バッチの実行に時間がかかる用途では、書き込みが割高でも1時間版のほうが結果的に安くなる場合があります。書き込み単価が上がる分を、読み込みヒットの回数で回収できるかで判断する形になります。

最小キャッシュトークン数の壁

Prompt Cachingで最初につまずきやすいのが、短いブロックはキャッシュ対象にならない点です。cache_controlを付けても、対象プレフィックスがモデルごとの最小トークン数に満たないと、キャッシュは書き込まれません。

公式ドキュメントの2026-05時点の表記では、最小トークン数はモデルで異なります。Opus 4.5 / 4.6 / 4.7やHaiku 4.5は4,096トークン、Sonnet 4.5 / 4.6やOpus 4.1は1,024トークンが下限とされています。正確な現行値はsourceUrlsの公式ドキュメントで確認してください。

ここで厄介なのは、閾値を下回ってもエラーは返らないことです。cache_controlは受け付けられるものの、レスポンスのcache_creation_input_tokensが0のまま=キャッシュされていない状態になります。「指定したのに効かない」ときは、まずこの最小トークン数を疑うと切り分けが早く進みます。

適用すべきシーン

Prompt Cachingが効くシーンの典型:

1. 長いsystem promptを持つチャットボット

カスタマーサポート / 社内Q&A / FAQボット等で、system promptに数千tokensのドメイン知識を持たせている場合。会話のターンが続くたびに同じsystem promptが再送信されるので、キャッシュ効果が大きい。

2. 大規模documentをcontextに持つRAG

100k tokensのドキュメントセットをcontextとして持たせ、複数のクエリを投げる場合。documentが共通でクエリだけ変わる構造はキャッシュ向き。

3. tools定義が長いagent

20+ toolsを定義したagentでは、tools定義だけで数千tokensを消費します。会話が続く間、tools定義は変わらないのでキャッシュ向き。

4. バッチ処理(同じinstructionsで多数のレコード処理)

「100件のレコードに対し、共通の評価promptで採点」のような構造はキャッシュの典型例。最初の1回でキャッシュを温めれば、99回はread単価で済みます。

適用すべきでないシーン

逆にキャッシュが効かない / 不利になるケース:

1. system promptが毎回変わる

会話ごとにsystem promptをユーザー入力で組み立てる場合、キャッシュキーが毎回異なるためヒットしません。書き込みコスト(1.25x)だけ無駄に発生します。

2. 1ユーザーあたりの呼び出しが1回限り

「1回prompt投げて終わり」のフロー(検索クエリ単発処理 等)では、書き込みコストが回収できません。

3. キャッシュTTLを超える間隔

5分版のキャッシュは、最後のヒットから5分経つと消えます。ユーザーが10分以上会話を中断するボットでは、キャッシュが頻繁に再書き込みされて効果が落ちます。

キャッシュブレークポイントとプレフィックス階層

cache_controlは「ここまでのプレフィックスをキャッシュする区切り」を意味します。この区切りをキャッシュブレークポイントと呼び、1リクエストにつき最大4つまで置けます。各ブレークポイントでは、その時点までの内容を累積したハッシュをキーに、ちょうど1つのキャッシュエントリが書き込まれます。

プレフィックスはtools → system → messagesの順で構成され、前の階層が変わると後ろの階層のキャッシュも無効になる従属関係があります。

この階層を踏まえると、変わりにくいものを前に、変わりやすいものを後ろに置く設計が効きます。tools定義とsystem promptを安定させ、ユーザー入力をmessages側に逃がすほど、キャッシュヒットが長く続きます。

20ブロックの先読み窓

キャッシュ読み込みは、現在のブレークポイントから最大20ブロック前までを遡って、過去のリクエストが書き込んだエントリを探します。会話が伸びて直近の書き込み位置が20ブロックより遠くなると、先読み窓から外れてヒットしなくなります。

会話が長く続くチャットでは、この窓落ちが起きやすくなります。対策として、前の書き込み位置の近くに2つ目のブレークポイントを追加で置くと、先読みが届く距離を保てます。最大4つまで使えるので、長い会話では複数のブレークポイントを段階的に配置する形になります。

実装パターン

Python SDKの例

from anthropic import Anthropic
 
client = Anthropic()
 
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "あなたは社内 FAQ ボットです。\n\n[ここに 5000 tokens の社内ナレッジ]",
            "cache_control": {"type": "ephemeral"},  # ← キャッシュ指定
        }
    ],
    messages=[{"role": "user", "content": "退職時の手続きを教えて"}],
)

cache_control を付けたブロックがキャッシュ対象になります。

TypeScript SDKの例

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const response = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "あなたは社内 FAQ ボットです。\n\n[5000 tokens]",
      cache_control: { type: "ephemeral" },
    },
  ],
  messages: [{ role: "user", content: "退職時の手続きを教えて" }],
});

キャッシュ効果の確認

APIレスポンスには usage フィールドが含まれ、キャッシュヒットの統計が確認できます。

{
  "usage": {
    "input_tokens": 50,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 5000,
    "output_tokens": 200
  }
}

• cache_creation_input_tokens: 今回の書き込みtokens
• cache_read_input_tokens: 今回の読み込みtokens
• input_tokens: 最後のブレークポイントより後ろの、キャッシュ対象外のtokens

ここで読み違えやすいのがinput_tokensです。これは入力全体ではなく、最後のブレークポイント以降のトークンだけを指します。キャッシュが効いているときはinput_tokensが小さく、cache_read_input_tokensが大きくなるのが正常な姿です。実際に処理された入力の合計は3つの合算(cache_read + cache_creation + input)で求まり、レート制限の見積もりにもこの合計を使います。

cache_creation_input_tokensが想定外に毎回大きいときは、ブレークポイントより前に変動する内容が紛れ込んでいるサインです。cache_read_input_tokensが常に0なら、最小トークン数を下回っているか、キャッシュキーが安定していない可能性があります。この2つの値を監視すると、効いていない原因の切り分けが進みます。

設計上の落とし穴

落とし穴1: 細かい変更でキャッシュキーがズレる

cache_control 付きブロック内の1文字でも変わるとキャッシュは無効になります。タイムスタンプや動的な日付をsystem promptに入れていると、毎回キャッシュ書き込みになります。

落とし穴2: 順序依存

キャッシュキーはtools → system → messagesの順序込みで計算されます。cache_control の位置を変えるとヒットしません。

落とし穴3: TTLを読み違える

5分は思ったより短い。バッチ処理を5分以内に終わらせる設計にしないと、途中でキャッシュが切れて再書き込みになります。

著者の運用方針

実運用で見えた指針:

1. 長いsystem prompt + 短いuser messageの組み合わせがある場面で、まず適用を検討する選択肢があります
2. 最初の1回が書き込みコスト(1.25x相当)になるため、その回収に必要なトラフィック量を試算しておくと判断しやすくなります
3. usage.cache_read_input_tokens を監視すると、想定通りキャッシュが効いているか確認できます
4. system promptは静的に保ち、動的な値はmessages側に逃がす設計だとキャッシュキーが安定しやすいです

まとめ

Prompt Cachingは「再利用するキャッシュキーが安定するか」が成立条件です。長い静的promptを持つRAG / チャットボット / バッチ処理では効きますが、promptが毎回変わる用途では効果が出ません。設計初期にこの判定だけ済ませておくと、後で「使ったが効かなかった」を避けられます。

関連記事:

• Claudeモデル選び方ガイド — モデル別の単価と組み合わせて、コスト最適化の全体像を掴む
• Anthropic Engineering — Context Engineeringの枠組み — キャッシュ前提のcontext設計を体系的に整理
• 長時間エージェントのハーネス設計 — compaction / 再利用前提の運用例