Prompt caching

一行要約

キャッシュは tools → system → messages の順に prefix として作られ、breakpoint は「リクエスト間で内容が同一である最後のブロック」に置く。ここを間違える（タイムスタンプなど変わるものに置く）と、prefix のハッシュが一致せずヒットしない。

要点

仕組み

指定した cache breakpoint までの prefix が最近のクエリでキャッシュ済みか確認する
あればそれを使う
なければ全体を処理し、応答の開始時に prefix をキャッシュする

既定のキャッシュ寿命は5分。書き込みまたは読み取りを行うリクエストの開始時点から測る（応答の終了時点ではない）。

価格

項目	倍率
5分キャッシュの書き込み	base input の 1.25倍
1時間キャッシュの書き込み	base input の 2倍
キャッシュ読み取り（両方とも）	base input の 0.1倍

→ 2回目のヒットで元が取れる。

breakpoint のルール

明示的な breakpoint は1リクエストあたり最大4つ
キャッシュ階層の順序は tools → system → messages。各段は前段の上に積み上がるので、ある段の変更はその段以降をすべて無効化する
breakpoint ごとに 20 ブロックの lookback window — 一致するキャッシュエントリを探して最大20位置まで遡る

Place cache_control on the last block whose prefix is identical across requests. Cache writes happen only at breakpoints. If the breakpoint is on content that changes (timestamps, per-request data), the prefix hash never matches and you won’t get cache hits. **cache_control は、リクエスト間で prefix が同一である最後のブロックに置け。**キャッシュへの書き込みは breakpoint でしか起きない。breakpoint を、変化する内容（タイムスタンプ、リクエストごとのデータ）の上に置くと、prefix のハッシュが一致せず、キャッシュヒットは得られない。

何がキャッシュを壊すか

変更	tools	system	messages
ツール定義	✘	✘	✘
web search のオン/オフ	✓	✘	✘
citations のオン/オフ	✓	✘	✘
speed 設定	✓	✘	✘
tool choice	✓	✓	✘
画像	✓	✓	✘
thinking パラメータ	モデル依存	モデル依存	✘
effort 設定	モデル依存	モデル依存	✘

（✓ = 保たれる、✘ = 無効化される）

キャッシュ可能な最小プロンプト長（モデル別）

モデル	最小トークン数
Opus 5 / Fable 5 / Mythos 5	512
Mythos Preview / Opus 4.7	2,048
Opus 4.6 / 4.5	4,096
Opus 4.8 / Sonnet 5 / Sonnet 4.6 / Sonnet 4.5 / Opus 4.1 / Sonnet 4	1,024
Haiku 4.5	4,096
Haiku 3.5	2,048

usage の読み方

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

cache_creation_input_tokens — 新規エントリ作成時に書き込まれたトークン
cache_read_input_tokens — このリクエストでキャッシュから読まれたトークン
input_tokens — 最後の breakpoint より後の、キャッシュされていないトークン

ベストプラクティス

多ターンの会話はまず automatic caching から始める
変更頻度の違うセクションを別々にキャッシュしたいときに明示的 breakpoint を使う
安定した内容（system 指示、例、大きな context、ツール）をキャッシュする
キャッシュ対象はプロンプトの先頭に置く
breakpoint は「リクエスト間で同一の最後のブロック」に置く
ヒット率を監視する
レイテンシに敏感なアプリでは pre-warming を使う（初回のキャッシュミスのペナルティを消す）

そのまま使える具体例

automatic caching（トップレベルの cache_control）:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works.",
    messages=[{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}],
)
print(response.usage.model_dump_json())

明示的 breakpoint（変わらない大きな文書の末尾に置く）:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": "You are an AI assistant tasked with analyzing legal documents."},
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [50 pages]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "What are the key terms and conditions in this agreement?"}],
)

1時間キャッシュ:

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

ツール定義のキャッシュ（最後のツールに置く）:

tools=[
    {"name": "get_weather", "description": "...", "input_schema": {}},
    {
        "name": "get_time",
        "description": "...",
        "input_schema": {},
        "cache_control": {"type": "ephemeral"},
    },
]

pre-warming（max_tokens=0 で書き込みだけ行う）:

# Fire this before users arrive to warm the shared system-prompt cache.
prewarm = client.messages.create(
    model="claude-opus-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)      # []

原典で言及されている関連文書

manage-tool-context — 「初日から prompt caching を有効にする」の出所
effort — effort 変更がキャッシュを無効化すること
context-editing — tool result clearing はキャッシュを壊し、thinking clearing は保つ
tool-search-tool — defer_loading がキャッシュを保つ仕組み
costs — Claude Code 側でのキャッシュ寿命（サブスクは1時間、usage credits 使用中は5分）
contextual-retrieval — prompt caching による前処理コストの削減

ai-docs

エクスプローラー