Claude APIのプロンプトキャッシュ｜書き方・料金・効かない時の確認

Claude APIでプロンプトキャッシュを使うには、リクエストの最上位に cache_control を1つ足すだけで始められます。何度も送る固定の指示や資料を一定時間とっておき、次の呼び出しでは基本の入力単価より安い「キャッシュ読み取り」の単価で使い回す仕組みで、既定の有効期間は5分です（プロンプトキャッシュの公式ページ）。Claude Sonnet 5.5のキャッシュ読み取り料金は、公式のリリースノートによると2026年10月7日に100万トークンあたり$0.20から$0.10へ引き下げられました（Claude Platformのリリースノート）。

この記事は、Claude APIで自分のアプリやスクリプトを作る人に向けて、キャッシュの書き方、有効期間の使い分け、料金の考え方、費用の試算、対応モデルと最小トークン数、効いているかの確認、効かない時の確認先を1ページにまとめたものです。Claude Codeの利用量や費用の見方は別の話題なので、そちらはClaude Codeの使用量とコストの確認方法を扱った記事を参照してください。Claude Sonnet 5.5そのものの仕様や使い分けはClaude Sonnet 5.5を紹介した記事にまとめているため、ここではキャッシュに関わる範囲に絞ります。

この記事の確認日は2026年10月16日です。公式ページの内容は更新されることがあるため、実際に使う前に本文中の公式リンクで最新の表記を見直してください。料金はAnthropicの料金ページにある米ドルの標準単価（100万トークンあたり）で、Batch APIの割引やデータ居住地の倍率が重なる場合は別に計算が必要です。「仮の例」と書いたコードや数字は、読み方を示すために私たちが置いた例であり、公式が示した実測値や推奨値ではありません。コードにAPIキーなどの実値は含めていません。

プロンプトキャッシュとは｜何を保存して、何が安くなるのか

プロンプトキャッシュとは、プロンプトの先頭から指定した位置までを保存し、次のリクエストで同じ先頭部分が続くときに読み取りとして使い回す機能で、公式は費用と遅延を減らせると説明しています。

公式の料金ページによると、プロンプトキャッシュは、大きなシステムプロンプトや資料、会話履歴を毎回処理し直す代わりに、以前処理した部分を再利用して費用と遅延を減らす機能です。使い方は2通りあり、リクエストの最上位に cache_control を1つ置く「自動キャッシュ」と、個別のコンテンツブロックに cache_control を置く「明示的なブレークポイント」です。公式は、ほとんどの用途で最初に試すのは自動キャッシュだとしています（料金ページのプロンプトキャッシュの節）。

キャッシュが使われる条件は厳密です。公式のプロンプトキャッシュのページは、キャッシュヒットには、cache_control を付けたブロックまでの全文と画像が完全に同じである必要があると説明しています（プロンプトキャッシュの公式ページ）。キャッシュ診断のページも、キャッシュが効くのは、プロンプトの先頭が直前のリクエストとバイト単位で同じ場合に限られ、ツールの並べ替え、システムプロンプトへの日時の差し込み、過去のメッセージの編集で、気づかないうちに無効になると説明しています（キャッシュ診断の公式ページ）。つまり、プロンプトを組み立てる側では「固定の部分を先頭に置き、毎回変わる部分を後ろに置く」設計が前提になります。

どんな呼び出しに向くかを、この記事の編集部が公式の説明に沿って整理すると、次のようになります。

呼び出しの形	キャッシュの考え方	根拠にした公式の記載
同じ長いシステムプロンプトを何度も送る	固定部分の末尾にブレークポイントを置く	静的な内容（ツール定義、システム指示、文脈、例）をプロンプトの先頭に置く
同じ資料に対して質問を重ねる	資料のブロックまでをキャッシュし、質問は後ろに置く	再利用する内容の末尾を cache_control で示す
会話が伸びていくチャット	自動キャッシュで、キャッシュ位置が会話とともに前へ進む	最後のキャッシュ可能なブロックに自動で置かれ、会話が伸びると移動する
呼び出しの間隔が5分を超える	1時間のキャッシュを検討する	5分では短い場合に1時間の有効期間がある（追加費用あり）
固定部分が最小トークン数に満たない	エラーなしでキャッシュされない	満たない要求は、エラーなしでキャッシュなしで処理される

書き方1｜リクエストの最上位に cache_control を置く自動キャッシュ

自動キャッシュとは、リクエストの最上位に cache_control: {"type": "ephemeral"} を1つ置くと、システムが最後のキャッシュ可能なブロックにキャッシュ位置を自動で置き、会話が伸びるとその位置を前へ動かす書き方です。

公式のリリースノートによると、自動キャッシュはMessages API向けに2026年2月19日に提供が始まりました。リクエスト本文に cache_control を1つ足すと、最後のキャッシュ可能なブロックが自動でキャッシュされ、手動でブレークポイントを管理する必要はない、と説明されています（リリースノート）。公式の最初の例はPythonで、messages.create の引数に cache_control={"type": "ephemeral"} を渡す形です。次のコードは、その形をClaude Sonnet 5.5向けに書き直した仮の例です。

# 仮の例：自動キャッシュ（公式の例をclaude-sonnet-5-5向けに書き直したもの）
import anthropic

client = anthropic.Anthropic()

LONG_INSTRUCTIONS = "（ここに512トークン以上の固定の指示や参考資料を入れる）"

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    cache_control={"type": "ephemeral"},
    system=LONG_INSTRUCTIONS,
    messages=[
        {"role": "user", "content": "この資料の要点を3行でまとめてください。"}
    ],
)
print(response.usage)

max_tokens は余裕を持たせて設定します。公式のSonnet 5.5向けプロンプトガイドは、思考のトークンも、思考の内容が返ってこない場合でも max_tokens に数えられると説明しているためです（Sonnet 5.5向けプロンプトガイド）。モデルIDは、Claude APIでは claude-sonnet-5-5 です（Sonnet 5.5のモデルページ）。

自動キャッシュには、知っておくと詰まりにくい決まりが2つあります。公式のプロンプトキャッシュのページによると、自動キャッシュと明示的なブレークポイントを併用すると、自動のキャッシュ位置は使えるブレークポイント4つのうち1つを使います。明示的なブレークポイントがすでに4つあると、自動キャッシュの分が残らず、APIは400エラーを返します。また、最後のブロックが自動キャッシュの対象にならない場合は、システムが静かに手前へたどって最も近い対象を探し、見つからなければキャッシュを行いません（プロンプトキャッシュの公式ページ）。

書き方2｜ブロックに cache_control を置く明示的なブレークポイント

明示的なブレークポイントとは、システムプロンプトの末尾のブロックやツール定義の最後など、キャッシュしたい範囲の終わりのブロックに cache_control を置く書き方で、1つのリクエストに最大4つ置けます。

固定部分と可変部分がはっきり分かれているなら、範囲を自分で指定できる明示的なブレークポイントが向きます。公式の「大きな文脈のキャッシュ」の例は、システムプロンプトを2つのテキストブロックに分け、2つ目（長い契約書の全文）に cache_control を置く形です。次のコードは、その考え方に沿った仮の例です。

# 仮の例：明示的なブレークポイント（system の2つ目のブロックまでをキャッシュ）
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "あなたは契約書の条文を点検するアシスタントです。",
        },
        {
            "type": "text",
            "text": "（ここに契約書の全文を入れる。このブロックまでがキャッシュされる）",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {"role": "user", "content": "第5条で注意すべき点を挙げてください。"}
    ],
)

ツール定義をキャッシュするときは、tools 配列の最後のツールに cache_control を置きます。公式のページによると、そのツールとそれより前に定義したすべてのツールが、ひとまとまりの先頭部分としてキャッシュされます（プロンプトキャッシュの公式ページ）。

# 仮の例：ツール定義のキャッシュ（最後のツールに cache_control を置く）
tools = [
    {
        "name": "get_order_status",
        "description": "注文番号から配送状況を返す",
        "input_schema": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
    {
        "name": "get_store_hours",
        "description": "店舗の営業時間を返す",
        "input_schema": {
            "type": "object",
            "properties": {"store_id": {"type": "string"}},
            "required": ["store_id"],
        },
        "cache_control": {"type": "ephemeral"},
    },
]

ブレークポイントの位置には、公式が示す考え方があります。再利用する静的な内容（ツール定義、システム指示、文脈、例）をプロンプトの先頭に置き、ブレークポイントは「リクエストをまたいで同じままの最後のブロック」に置きます。毎回変わる日時やリクエストごとの情報、送られてきたメッセージは、ブレークポイントより後ろに置く、という考え方です。キャッシュ診断のページも、システムプロンプトに日時やリクエストIDを差し込むと変化が起きるため、システムプロンプトは常に同じ内容にして、動的なデータはキャッシュ位置より後ろの最初のuserメッセージに移すよう勧めています（キャッシュ診断の公式ページ）。

会話が長くなると、もう1つ注意点があります。公式は、システムが1つのブレークポイントにつき最大20個の位置を手前へさかのぼって一致するキャッシュを探す、と説明しています。さかのぼって見つけられるのは、以前のリクエストがすでに書き込んだ位置だけです。会話が伸びてブレークポイントが最後の書き込みから20ブロック以上先へ進むと、見つからなくなります。その場合は、最初から手前に2つ目のブレークポイントを置いておき、そこに書き込みが積み上がるようにします（プロンプトキャッシュの公式ページ）。

有効期間｜5分と1時間の使い分けと並列リクエストの注意

キャッシュの有効期間は既定で5分で、キャッシュが使われるたびに追加費用なしで更新されます。5分では短い場合に、追加費用のかかる1時間の有効期間を選べます。

公式のプロンプトキャッシュのページによると、既定のキャッシュは5分間有効で、キャッシュの内容が使われるたびに追加費用なしで更新されます。有効期間は、キャッシュを書き込む、または読み取るリクエストの「開始時点」から数え、応答が終わった時点からではありません。5分では短い場合は、1時間のキャッシュを追加費用のうえで選べ、指定は次のとおりです。

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

どちらを選ぶかについて、公式は次のように説明しています。システムプロンプトを5分より短い間隔で頻繁に使うなら、5分のキャッシュのままにします。使うたびに追加費用なしで更新され続けるためです。1時間のキャッシュが向くのは、5分よりは空くが1時間以内には再び使う場合です。たとえば、エージェントの補助処理が5分を超える場合や、ユーザーの返信が5分以内に来ないことが多い長い会話を保存する場合です。そのほか、後続のリクエストが5分を超えて送られても遅延を小さくしたい場合や、キャッシュヒットがレート制限に数えられないことを利用してレート制限の消費を抑えたい場合も挙げられています（1時間キャッシュの節）。

1つのリクエストで1時間と5分の両方を使うこともできますが、順序の決まりがあります。公式によると、有効期間が長いキャッシュ（1時間）は、短いキャッシュ（5分）より前に置く必要があります（プロンプトキャッシュの公式ページ）。たとえば、ほとんど変わらない大きな資料を1時間、直近の会話履歴を5分、という組み合わせは、資料が前、履歴が後ろの順になっていれば成り立ちます。

並列で呼び出す場合にも落とし穴があります。公式は、キャッシュのエントリが使えるようになるのは最初の応答が始まってからだと説明しています。並列のリクエストでキャッシュヒットが欲しい場合は、最初の応答を待ってから後続のリクエストを送ります（プロンプトキャッシュの公式ページ）。同じ資料に同時に10件の質問を投げると、最初の応答が始まる前に送った分はキャッシュを読めない可能性があるため、1件目を先に送り、応答が始まってから残りを送る順番が安全です。

料金の考え方｜書き込みと読み取りの倍率、Sonnet 5.5の引き下げ

プロンプトキャッシュの料金は、基本の入力単価に対する倍率で決まり、5分の書き込みが1.25倍、1時間の書き込みが2倍、読み取りは多くのモデルで0.1倍、Claude Sonnet 5.5とClaude Opus 5.5では0.05倍です。

公式の料金ページによると、プロンプトキャッシュの倍率は次のとおりです。5分の書き込みは基本入力単価の1.25倍、1時間の書き込みは2倍、キャッシュ読み取り（ヒット）は多くのモデルで0.1倍です。読み取りの例外として、Claude Fable 5.1とClaude Mythos 5.1は0.025倍、Claude Opus 5.5とClaude Sonnet 5.5は0.05倍と書かれています。書き込みトークンは内容を最初に保存するときに、読み取りトークンは後続のリクエストが保存済みの内容を取り出すときに課金されます。また、これらの倍率はBatch APIの割引やデータ居住地の倍率と重なって適用されます（料金ページのプロンプトキャッシュの節）。

主なモデルのキャッシュ関連の単価を、2026年10月16日に確認した料金ページの記載のとおりに並べます（Claude API、米ドル、100万トークンあたり）。Claude Haiku 5.5はプロンプトが10万トークン以下の場合の単価で、10万トークンを超えるリクエストはより高い単価になります。単価の最新値は料金ページのモデル別料金の表で確認してください。

モデル	基本の入力	5分の書き込み	1時間の書き込み	キャッシュ読み取り
Claude Sonnet 5.5	$2	$2.50	$4	$0.10
Claude Sonnet 5	$2	$2.50	$4	$0.20
Claude Opus 5.5	$4	$5	$8	$0.20
Claude Haiku 5.5（10万トークン以下）	$0.10	$0.125	$0.20	$0.01
Claude Fable 5.1	$10	$12.50	$20	$0.25

各モデルの位置づけは、Claude Opus 5.5を紹介した記事やClaude Haiku 5.5を紹介した記事でも整理しています。

Claude Sonnet 5.5の引き下げについて、公式のリリースノートは2026年10月7日付で、Claude Sonnet 5.5のプロンプトキャッシュ読み取りを100万トークンあたり$0.20から$0.10へ下げたと記載しています。基本の入力単価に対する倍率では、0.1倍から0.05倍への変更で、キャッシュ書き込みとそのほかの料金は変わっていません（リリースノート）。Sonnet 5.5の変更点ページも、Sonnet 5と同じ価格だが、プロンプトキャッシュの読み取りだけは$0.10で、Sonnet 5の半分だと説明しています（Sonnet 5.5の変更点ページ）。確認日の時点では、リリースノート、料金ページ、モデルページ（Sonnet 5.5のモデルページ）、発表ページ（Sonnet 5.5の発表ページ）のいずれも、読み取りを$0.10としています。Sonnet 5.5について、10月7日より前に書かれた資料にある読み取り$0.20は、変更前の単価です。

費用の試算｜キャッシュあり・なしの違いを仮の例で計算する

キャッシュの費用は、固定部分のトークン数に倍率をかけて計算でき、Claude Sonnet 5.5の5分キャッシュでは、書き込みを1回行った後に1回でも読み取りが入れば、キャッシュなしより安くなります。

次の計算は、公式の単価を使った四則演算の仮の例で、実際の請求額や公式が示した実測値ではありません。条件は、Claude APIの標準料金でClaude Sonnet 5.5を使い、固定部分（システムプロンプトと資料）が20,000トークン、リクエストごとに増える新しい入力が500トークン、100回のリクエストがすべて前回から5分以内に続く場合です。出力トークンの費用はキャッシュの有無で変わらないため、入力側だけを比べます。単価は料金ページの値（入力$2、5分の書き込み$2.50、読み取り$0.10、いずれも100万トークンあたり）です。

パターン	計算	入力側の合計
キャッシュなし	100回 × 20,500トークン = 2,050,000トークン × $2 ÷ 100万	$4.10
キャッシュあり（1回目）	書き込み 20,000トークン × $2.50 ÷ 100万 = $0.05、新しい入力 500トークン × $2 ÷ 100万 = $0.001	$0.051
キャッシュあり（2〜100回目の99回）	読み取り 1,980,000トークン × $0.10 ÷ 100万 = $0.198、新しい入力 49,500トークン × $2 ÷ 100万 = $0.099	$0.297
キャッシュあり（100回の合計）	$0.051 + $0.297	$0.348

この仮の例では、入力側の費用は$4.10から$0.348になり、キャッシュなしの約8.5%です。読み取りが変更前の$0.20だった場合は、読み取りの部分が1,980,000トークン × $0.20 ÷ 100万 = $0.396になり、合計は$0.546です。引き下げで、この条件の100回あたり$0.198（読み取りの部分の半分）安くなる計算です。

次に、キャッシュを使うべきかどうかの損益分岐を考えます。固定部分の基本入力単価を1とした倍率で、同じ内容をN回送る場合を比べます（Claude Sonnet 5.5、書き込み後は読み取りだけが続き、すべて有効期間内と仮定）。キャッシュなしはN、5分のキャッシュは 1.25 + 0.05 ×（N−1）、1時間のキャッシュは 2 + 0.05 ×（N−1）です。倍率の根拠は料金ページの1.25倍、2倍、0.05倍です。

送る回数N	キャッシュなし	5分のキャッシュ	1時間のキャッシュ
1回	1.00	1.25	2.00
2回	2.00	1.30	2.05
3回	3.00	1.35	2.10
5回	5.00	1.45	2.20
10回	10.00	1.70	2.45
20回	20.00	2.20	2.95

表から、1回しか使わない固定部分にキャッシュを付けると、書き込みの分だけ高くなることが分かります。2回目の読み取りが入れば5分のキャッシュは安くなり、1時間のキャッシュは3回送る時点で安くなります。公式の料金ページも、5分の有効期間では読み取り1回、1時間の有効期間では読み取り2回で元が取れる、と説明しています。

呼び出しの間隔にも注意が必要です。5分のキャッシュは、前回の使用から5分を超えて空くと失効するため、間隔が6分の呼び出しでは毎回が書き込みになります。そのときの固定部分の費用は、毎回1.25倍です。キャッシュなしの1.00倍より高くなります。同じ6分間隔の10回でも、1時間のキャッシュなら 2 + 0.05 × 9 = 2.45 です（5分のキャッシュは1.25 × 10 = 12.50、キャッシュなしは10.00）。間隔が5分を超えそうな用途では、1時間のキャッシュを検討する理由がここにあります。

対応モデルと最小トークン数｜短いプロンプトはキャッシュされない

プロンプトキャッシュはすべての提供中のClaudeモデルで使えますが、モデルごとに最小のキャッシュ可能トークン数があり、それに満たない部分はエラーなしでキャッシュされません。

公式のプロンプトキャッシュのページによると、自動キャッシュも明示的なブレークポイントも、すべての提供中のClaudeモデルで対応しています。最小のキャッシュ可能トークン数は、Claude Sonnet 5.5、Claude Opus 5.5、Claude Haiku 5.5、Claude Fable 5.1などで512トークンです。最小値に満たない要求は、キャッシュなしで処理され、エラーも出ません（プロンプトキャッシュの公式ページ）。同じ内容でもモデルによって結果が変わるのは、次の表のとおりです。

最小のキャッシュ可能トークン数	公式が挙げているモデルの例
512トークン	Claude Sonnet 5.5、Claude Opus 5.5、Claude Haiku 5.5、Claude Fable 5.1
1,024トークン	Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.8
2,048トークン	Claude Opus 4.7
4,096トークン	Claude Opus 4.5、Claude Opus 4.6、Claude Haiku 4.5

たとえば、固定部分が700トークンのプロンプトは、公式の表ではSonnet 5.5（512トークン）ならキャッシュの対象になり、Sonnet 5（1,024トークン）では対象になりません。Sonnet 5から切り替えると、512トークン以上1,024トークン未満の固定部分は、キャッシュの対象に加わります（Sonnet 5.5の変更点ページ）。切り替えの手順そのものはClaude Sonnet 5.5への移行手順を扱った記事にまとめています。公式は、プロンプトが最小値にわずかに届かない場合は、キャッシュする内容を増やして最小値に届かせることが、よく費用の面で有効だとも書いています。

効いているかの確認｜usageの3つの項目の読み方

キャッシュが効いているかは、応答の usage にある cache_creation_input_tokens、cache_read_input_tokens、input_tokens の3つで確認でき、前2つがどちらも0なら、そのプロンプトはキャッシュされていません。

公式のプロンプトキャッシュのページは、キャッシュの状況をusageの3項目で確認するよう説明しています。cache_creation_input_tokens は新しいエントリとしてキャッシュに書き込んだトークン数、cache_read_input_tokens はこのリクエストでキャッシュから取り出したトークン数、input_tokens は最後のブレークポイントより後ろで、キャッシュの読み書きに使われなかった入力トークン数です。入力全体は、読み取り、書き込み、input_tokens の合計になります。ストリーミングの場合は message_start イベントに入っています。2つのキャッシュ項目がどちらも0なら、キャッシュされていません。最小のトークン数を満たしていないことが原因として考えられる、と公式は説明しています（キャッシュ状況の確認の節）。

# 仮の例：usage の3項目を確認する
u = response.usage
print("書き込み:", u.cache_creation_input_tokens)
print("読み取り:", u.cache_read_input_tokens)
print("キャッシュ外の入力:", u.input_tokens)

前の節の費用の試算と同じ条件（固定部分20,000トークン、新しい入力500トークン）なら、usageは次のように変わるはずです。これも仮の例です。

リクエスト	cache_creation_input_tokens	cache_read_input_tokens	input_tokens	読み方
1回目	20,000	0	500	固定部分が書き込まれた
2回目（5分以内）	0	20,000	500	固定部分がキャッシュから読まれた
3回目（6分後に失効）	20,000	0	500	失効して再び書き込みになった

2回目で読み取りが0のままなら、固定部分が前回と一致していないか、最小のトークン数に届いていないか、有効期間を過ぎているかのいずれかです。次の節で、原因を順に絞り込みます。

効かない時の確認｜原因の候補と診断APIの使い方

キャッシュが効かない原因の多くは、先頭部分が前回と変わっていること、有効期間や最小トークン数を満たしていないこと、並列で同時に送っていることのいずれかで、公式のキャッシュ診断を使うとどこで食い違ったかを確認できます。

公式のプロンプトキャッシュのページには、原因を確認するためのチェックリストがあります。そこにある項目と、キャッシュ診断のページにある理由の種類を、この記事の編集部が原因の候補として表にまとめました（トラブルシューティングの節）。

疑う点	起きること	確認と対処
固定部分が最小のトークン数に満たない	エラーなしでキャッシュされない	モデルごとの最小値と比べる。usageの2項目が0なら該当しやすい
呼び出しの間隔が有効期間を超えた	5分（既定）を過ぎるとキャッシュが使えない	間隔を測る。空くなら1時間のキャッシュを検討する
システムプロンプトに日時やリクエストIDを入れている	先頭が毎回変わり、一致しない（診断の理由は system_changed）	システムプロンプトを一定にし、動的な情報は最初のuserメッセージへ移す
ツール定義の追加・削除・並べ替え・スキーマの直列化の揺れ	ツール定義の変更はキャッシュ全体を無効にする（診断の理由は tools_changed）	毎回同じ順序、同じ内容で送る。キーの並びを固定する
過去のメッセージを編集・削除・並べ替えた	メッセージ部分が一致しない（診断の理由は messages_changed）	履歴は追記だけにし、assistantの内容とツール結果はそのまま返す
tool_choice、画像、thinking、effortを会話の途中で変えた	メッセージ部分のキャッシュが無効になる	会話の間は同じ設定に固定する
同じ内容を並列で同時に送った	最初の応答が始まるまでキャッシュのエントリが使えない	1件目の応答が始まってから後続を送る
ブレークポイントが最後の書き込みから20ブロック以上先にある	さかのぼる範囲を外れ、見つからない	手前に2つ目のブレークポイントを置く
SwiftやGoなどでツール入力のキーの順序が毎回ばらつく	JSON変換でキー順が変わり、キャッシュが壊れる	キーの並びが安定するよう直列化する
モデルを切り替えた	キャッシュはモデルごとに分かれる（診断の理由は model_changed）	キャッシュする会話の間はモデルを固定する
ワークスペースが違う	キャッシュはワークスペースごとに分かれる	同じワークスペースのAPIキーで呼び出す

表の根拠は、プロンプトキャッシュの公式ページ（ツール定義、tool_choice、画像、thinking、effort、速度設定の変更による無効化と、トラブルシューティングの一覧）、キャッシュ診断のページ（理由の種類）です。ワークスペースについては、公式は、キャッシュはワークスペースごとに分かれ、同じ組織の中でもワークスペースが違えば共有されないと説明しています。Claude APIで複数のワークスペースを使う場合は、キャッシュの戦略をこの違いを踏まえて見直すよう書かれています（プロンプトキャッシュの公式ページ）。

原因が表から絞れないときは、キャッシュ診断が使えます。公式のキャッシュ診断のページによると、リクエストに diagnostics オブジェクトを付け、前の応答の id を previous_message_id に渡すと、APIが2つのリクエストを比べて、モデル、システムプロンプト、ツール、メッセージ履歴のどこで食い違ったかを応答の diagnostics に返します。最初のターンは previous_message_id を null にして、記録の対象に加わります。2026年9月23日のリリースノートには、キャッシュ診断はClaude APIでベータを終え、ベータヘッダーが不要になったと記載されています（キャッシュ診断の公式ページ）。Claude APIだけの機能で、Amazon BedrockとGoogle Cloudでは使えません。

# 仮の例：キャッシュ診断（公式のPythonの例の形に沿って、claude-sonnet-5-5向けに書き直したもの）
r1 = client.beta.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    cache_control={"type": "ephemeral"},
    system=LONG_INSTRUCTIONS,
    messages=[{"role": "user", "content": "1つ目の質問"}],
    diagnostics={"previous_message_id": None},  # 最初のターンはNone
)

r2 = client.beta.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    cache_control={"type": "ephemeral"},
    system=LONG_INSTRUCTIONS,
    messages=[
        {"role": "user", "content": "1つ目の質問"},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "2つ目の質問"},
    ],
    diagnostics={"previous_message_id": r1.id},
)

d = r2.diagnostics
if d is not None and d.cache_miss_reason is not None:
    print(d.cache_miss_reason.type)  # system_changed など

診断の結果とusageは、組み合わせて読みます。公式のページは、診断が null（食い違いなし）で読み取りが多ければ想定どおり、診断が null なのに読み取りが少ないか0なら、リクエストは同じなのにキャッシュのエントリが残っていなかったと解釈し、呼び出しの間隔を詰めるか1時間のキャッシュを検討するよう勧めています。診断に system_changed などの変更の理由が出ていて読み取りが少ないなら、リクエスト側の問題なので、理由に示された箇所を直します。理由は最初に食い違った場所だけが返るため、先にそれを直します（診断とusageを合わせて読む節）。

Claude Sonnet 5.5で特に注意すること｜effortの変更とthinkingブロック

Claude Sonnet 5.5では、トップレベルのeffortをリクエストの間で変えるとプロンプトキャッシュが無効になるため、会話の途中でeffortを変えたいときは、キャッシュを保つ「メッセージごとのeffort」（ベータ）を使います。

公式のSonnet 5.5向けプロンプトガイドによると、トップレベルの effort の値をリクエストの間で変えると、プロンプトキャッシュが無効になります。会話の途中でレベルを変えたいときは、キャッシュを保てる「メッセージごとのeffort」（ベータ）を使い、変更は次の変更まで以降のすべてのターンに続きます（Sonnet 5.5向けプロンプトガイド）。プロンプトキャッシュのページの無効化の表にも、メッセージごとのeffortに対応するモデルでは、role: "system" のメッセージで運ぶeffortの変更はキャッシュされた先頭部分を保つ、と記載されています。

思考ブロックにも関わりがあります。同じ無効化の表によると、Claude Sonnet 5.5などの思考ブロックを、その要求で保持されない形でAPIが取り除くと（たとえば、読めないモデルに再送した場合）、その位置から後ろのキャッシュされた先頭部分が変わります。読めるモデルへ変更せずに戻したブロックは、キャッシュを保ちます（プロンプトキャッシュの公式ページ）。そのため、キャッシュを重視する会話では、モデルを途中で切り替えず、履歴を追記だけにする運用が合います。Sonnet 5.5への切り替え全体の注意は、Claude Sonnet 5.5への移行手順を扱った記事を参照してください。

よくある質問（FAQ）

Q1. Claude APIのプロンプトキャッシュは何分間有効ですか。

既定は5分で、使われるたびに追加費用なしで更新されます。5分では短い場合は、追加費用のかかる1時間の有効期間を ttl に "1h" を指定して選べます（プロンプトキャッシュの公式ページ）。

Q2. Claude Sonnet 5.5のキャッシュ読み取りはいくらですか。

Claude APIの料金ページでは、2026年10月16日の確認時点で100万トークンあたり$0.10です。2026年10月7日に$0.20から引き下げられました（リリースノート）。5分の書き込みは$2.50、1時間の書き込みは$4で、変更はありません（料金ページ）。

Q3. 何トークンからキャッシュされますか。

Claude Sonnet 5.5では512トークンです。Claude Sonnet 5は1,024トークンで、モデルによって最小値が違います。満たない場合はエラーなしでキャッシュされません（プロンプトキャッシュの公式ページ）。

Q4. cache_controlを付けたのにキャッシュが効きません。何を確認すればよいですか。

まずusageの cache_creation_input_tokens と cache_read_input_tokens を見て、どちらも0なら最小のトークン数を疑います。そのうえで、システムプロンプトへの日時の差し込み、ツールの並べ替え、履歴の編集、有効期間の超過を確認し、それでも分からなければキャッシュ診断を使います（キャッシュ診断の公式ページ）。

Q5. モデルを切り替えても、キャッシュは引き継がれますか。

引き継がれません。公式のキャッシュ診断のページは、キャッシュはモデルごとに分かれるとして、キャッシュする会話の間はモデルを一定にするよう勧めています（キャッシュ診断の公式ページ）。

Q6. Batch APIとプロンプトキャッシュは一緒に使えますか。

料金の面では、キャッシュの倍率はBatch APIの割引やデータ居住地の倍率と重なって適用されると、公式の料金ページに書かれています（料金ページ）。バッチでのキャッシュの効き方の細かい条件は、Batch APIの公式ページで確認してください。

Q7. 1時間のキャッシュは常に5分のキャッシュより得ですか。

そうとは限りません。公式は、システムプロンプトを5分より短い間隔で頻繁に使うなら5分のキャッシュのままにするよう勧めています。5分のキャッシュは使うたびに追加費用なしで更新されるためです。1時間のキャッシュは、5分を超えて空く用途で効果が出ます（1時間キャッシュの節）。

Q8. 別のワークスペースのキャッシュは使えますか。

使えません。公式によると、Claude APIではキャッシュがワークスペースごとに分かれ、同じ組織の中でもワークスペースが違えば共有されません。組織が違う場合も共有されません（プロンプトキャッシュの公式ページ）。

まとめ｜固定部分を先頭に置き、usageで確かめながら使う

プロンプトキャッシュは、固定の指示や資料を先頭に置き、リクエストの最上位か末尾のブロックに cache_control を付けて使います。有効期間は既定で5分、間隔が空く用途では1時間を選びます。料金は書き込みが1.25倍と2倍、読み取りがClaude Sonnet 5.5では0.05倍で、2026年10月7日に読み取りが$0.20から$0.10へ引き下げられました（確認日は2026年10月16日、リリースノート）。この記事の仮の例では、20,000トークンの固定部分を100回送る入力側の費用が$4.10から$0.348になる計算でした。

導入したあとは、usageの cache_creation_input_tokens と cache_read_input_tokens を毎回見て、2回目以降に読み取りが入っているかを確かめます。効かないときは、最小のトークン数、有効期間、先頭部分の変化、並列送信の順に確認し、必要ならキャッシュ診断で食い違った場所を特定します。モデルごとの料金や使い分けを広く確認したい方は、Claudeの料金・モデル・始め方を解説した記事も合わせて参考にしてください。