プロンプトキャッシング

「prompt caching」（プロンプトキャッシング）は、API がプロンプト内の特定のプレフィックスから処理を再開できるようにすることで、API の使用を最適化します。これにより、反復的なタスクや一貫した要素を含むプロンプトの処理時間とコストが大幅に削減されます。

プロンプトキャッシングを有効にするには、2つの方法があります。

• 自動キャッシング： リクエストのトップレベルに単一の cache_control フィールドを追加します。システムは最後のキャッシュ可能なブロックに自動的にキャッシュブレークポイントを適用し、会話が長くなるにつれてそれを前方に移動させます。増え続けるメッセージ履歴を自動的にキャッシュしたいマルチターンの会話に最適です。
• 明示的なキャッシュブレークポイント： 個々のコンテンツブロックに直接 cache_control を配置し、キャッシュする内容をきめ細かく制御します。

最も簡単な始め方は自動キャッシングです。

client = anthropic.Anthropic()

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

自動キャッシングでは、システムは最後のキャッシュ可能なブロックまで（そのブロックを含む）のすべてのコンテンツをキャッシュします。同じプレフィックスを持つ後続のリクエストでは、キャッシュされたコンテンツが自動的に再利用されます。

プロンプトキャッシングの仕組み

プロンプトキャッシングを有効にしてリクエストを送信すると、次のように処理されます。

1. システムは、指定されたキャッシュブレークポイントまでのプロンプトプレフィックスが、最近のクエリによってすでにキャッシュされているかどうかを確認します。
2. 見つかった場合は、キャッシュされたバージョンを使用し、処理時間とコストを削減します。
3. 見つからない場合は、プロンプト全体を処理し、レスポンスが開始された時点でプレフィックスをキャッシュします。

これは特に次のような場合に役立ちます。

• 多数の例を含むプロンプト
• 大量のコンテキストや背景情報
• 一貫した指示を伴う反復的なタスク
• 長いマルチターンの会話

デフォルトでは、キャッシュの有効期間は5分です。キャッシュされたコンテンツが使用されるたびに、キャッシュは追加コストなしで更新されます。

有効期間は、キャッシュエントリを書き込むまたは読み取るリクエストの開始時点から測定され、そのレスポンスの終了時点からではありません。レスポンスの生成に費やされた時間も有効期間に含まれます。たとえば、レスポンスのストリーミングに4分かかる場合、同じキャッシュ済みプレフィックスを再利用する後続のリクエストは、そのレスポンスの完了から約1分以内に開始する必要があります。

料金

プロンプトキャッシングには独自の料金体系があります。次の表は、サポートされている各モデルの100万トークンあたりの料金を示しています。

モデル	基本トークン		プロンプトキャッシュ
名前	入力	出力	5 分キャッシュ書き込み	1 時間の書き込み	ヒットとリフレッシュ
Claude Fable 5.2For demanding reasoning and long-horizon agentic work	$8 / MTok	$40 / MTok	$10 / MTok	$16 / MTok	$0.20 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	$4 / MTok	$20 / MTok	$5 / MTok	$8 / MTok	$0.20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.10 / MTok2
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing	$0.10 / MTok100,000 トークン以下のプロンプトの場合	$0.50 / MTok	$0.125 / MTok	$0.20 / MTok	$0.01 / MTok
	$0.50 / MTok100,000 トークンを超えるプロンプトの場合	$2.50 / MTok	$0.625 / MTok	$1 / MTok	$0.05 / MTok
その他のモデル
Claude Mythos 5.2	$8 / MTok	$40 / MTok	$10 / MTok	$16 / MTok	$0.20 / MTok1
Claude Fable 5.1	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Mythos 5.1	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Fable 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Mythos 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Opus 5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.8	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.7	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.6	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.1	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Opus 4	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Sonnet 5	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Sonnet 4.6	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4.5	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Haiku 4.5	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / MTok

^{1 Claude Fable 5.2、Claude Mythos 5.2、Claude Fable 5.1、Claude Mythos 5.1 のキャッシュヒットおよび更新は、基本入力料金の 0.025x で課金されます。}

^{2 Claude Opus 5.5、Claude Sonnet 5.5 のキャッシュヒットおよび更新は、基本入力料金の 0.05x で課金されます。}

^{他のすべてのモデルには、標準の倍率 0.1x が適用されます。}

サポートされているモデル

プロンプトキャッシング（自動および明示的の両方）は、すべてのアクティブな Claude モデルでサポートされています。

自動キャッシング

自動キャッシングは、プロンプトキャッシングを有効にする最も簡単な方法です。個々のコンテンツブロックに cache_control を配置する代わりに、リクエスト本文のトップレベルに単一の cache_control フィールドを追加します。システムは最後のキャッシュ可能なブロックに自動的にキャッシュブレークポイントを適用します。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())

マルチターン会話における自動キャッシングの仕組み

自動キャッシングでは、会話が長くなるにつれてキャッシュポイントが自動的に前方に移動します。新しいリクエストごとに最後のキャッシュ可能なブロックまでのすべてがキャッシュされ、以前のコンテンツはキャッシュから読み取られます。

キャッシュブレークポイントは各リクエストの最後のキャッシュ可能なブロックに自動的に移動するため、会話が長くなっても cache_control マーカーを更新する必要はありません。

TTL のサポート

デフォルトでは、自動キャッシングは5分のTTLを使用します。基本入力トークン価格の2倍で1時間のTTLを指定することもできます。

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

ブロックレベルのキャッシングとの組み合わせ

自動キャッシングは明示的なキャッシュブレークポイントと互換性があります。併用した場合、自動キャッシュブレークポイントは利用可能な4つのブレークポイントスロットのうち1つを使用します。

これにより、両方のアプローチを組み合わせることができます。たとえば、明示的なブレークポイントを使用してシステムプロンプトをキャッシュし、会話は自動キャッシングで処理できます。

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

変わらない点

自動キャッシングは同じ基盤となるキャッシングインフラストラクチャを使用します。料金、最小トークンしきい値、コンテキストの順序要件、20ブロックのルックバックウィンドウはすべて、明示的なブレークポイントの場合と同様に適用されます。

エッジケース

• 最後のブロックにすでに同じTTLの明示的な cache_control がある場合、自動キャッシングは何も行いません。
• 最後のブロックに異なるTTLの明示的な cache_control がある場合、API は400エラーを返します。
• 明示的なブロックレベルのブレークポイントがすでに4つ存在する場合、API は400エラーを返します（自動キャッシングに使えるスロットが残っていないため）。
• 最後のブロックが自動キャッシュブレークポイントの対象として適格でない場合、システムは暗黙的に後方へたどり、最も近い適格なブロックを探します。見つからない場合、キャッシングはスキップされます。

明示的なキャッシュブレークポイント

キャッシングをより細かく制御するには、個々のコンテンツブロックに直接 cache_control を配置できます。これは、異なる頻度で変更される異なるセクションをキャッシュする必要がある場合や、キャッシュする内容をきめ細かく制御する必要がある場合に便利です。

プロンプトの構成

静的なコンテンツ（ツール定義、システム指示、コンテキスト、例）をプロンプトの先頭に配置します。cache_control パラメータを使用して、キャッシュ対象となる再利用可能なコンテンツの終わりをマークします。

キャッシュプレフィックスは、tools、system、messages の順序で作成されます。この順序は、各レベルが前のレベルの上に構築される階層を形成します。

自動プレフィックスチェックの仕組み

静的コンテンツの末尾にキャッシュブレークポイントを1つだけ使用すれば、システムは以前のリクエストがすでにキャッシュに書き込んだ最長のプレフィックスを自動的に見つけます。この仕組みを理解すると、キャッシング戦略の最適化に役立ちます。

3つの基本原則：

1. キャッシュ書き込みはブレークポイントでのみ発生します。 ブロックに cache_control をマークすると、ちょうど1つのキャッシュエントリ、つまりそのブロックで終わるプレフィックスのハッシュが書き込まれます。システムはそれより前の位置にはエントリを書き込みません。ハッシュは累積的で、ブレークポイントまで（ブレークポイントを含む）のすべてを対象とするため、ブレークポイント以前のいずれかのブロックを変更すると、次のリクエストでは異なるハッシュが生成されます。

2. キャッシュ読み取りは、以前のリクエストが書き込んだエントリを後方に向かって探します。 各リクエストで、システムはブレークポイントでのプレフィックスハッシュを計算し、一致するキャッシュエントリがあるかを確認します。存在しない場合は1ブロックずつ後方へたどり、それより前の各位置のプレフィックスハッシュがすでにキャッシュにあるものと一致するかを確認します。システムが探しているのは以前の書き込みであり、安定したコンテンツではありません。

3. ルックバックウィンドウは20ブロックです。 システムは各ブレークポイントについて、ブレークポイント自体を最初の1つとして数え、最大20の位置を確認します。そのウィンドウ内で一致するエントリが見つからない場合、確認は停止します（または、次の明示的なブレークポイントがあればそこから再開します）。Claude API では、連続する tool_use ブロックの並びは1つの位置として数えられ、連続する tool_result ブロックの並びも同様です。そのため、多数の並列ツール呼び出しを含むターンがあっても、それだけで前のリクエストのエントリがウィンドウの外に押し出されることはありません。

例：成長する会話でのルックバック

ターンごとに新しいブロックを追加し、各リクエストの最後のブロックに cache_control を設定します。

• ターン1： 10ブロック、ブレークポイントはブロック10。以前のキャッシュエントリは存在しません。システムはブロック10にエントリを書き込みます。
• ターン2： 15ブロック、ブレークポイントはブロック15。ブロック15にはエントリがないため、システムはブロック10まで後方へたどり、ターン1のエントリを見つけます。ブロック10でキャッシュヒットします。システムはブロック11から15のみを新たに処理し、ブロック15に新しいエントリを書き込みます。
• ターン3： 35ブロック、ブレークポイントはブロック35。システムは20の位置（ブロック35から16）を確認しますが、何も見つかりません。ブロック15にあるターン2のエントリはウィンドウの1つ外側にあるため、キャッシュヒットしません。ブロック15に2つ目のブレークポイントを追加すると、そこから2つ目のルックバックウィンドウが始まり、ターン2のエントリが見つかります。

よくある間違い：リクエストごとに変わるコンテンツへのブレークポイント設定

プロンプトに大きな静的システムコンテキスト（ブロック1から5）があり、その後にタイムスタンプとユーザーメッセージを含むリクエストごとのブロック（ブロック6）が続くとします。ブロック6に cache_control を設定します。

• リクエスト1： ブロック6でキャッシュ書き込み。ハッシュにはタイムスタンプが含まれます。
• リクエスト2： タイムスタンプが異なるため、ブロック6のプレフィックスハッシュも異なります。ルックバックはブロック5、4、3、2、1をたどりますが、システムはそれらの位置に一度もエントリを書き込んでいません。キャッシュヒットはありません。毎回のリクエストで新たなキャッシュ書き込みの料金が発生し、読み取りは一度も得られません。

ルックバックは、ブレークポイントより前にある安定したコンテンツを見つけてキャッシュするわけではありません。以前のリクエストがすでに書き込んだエントリを見つけるものであり、書き込みはブレークポイントでのみ発生します。cache_control をリクエスト間で同じままである最後のブロックであるブロック5に移動すると、後続のすべてのリクエストがキャッシュされたプレフィックスを読み取ります。自動キャッシングにも同じ問題があります。自動キャッシングは最後のキャッシュ可能なブロックにブレークポイントを配置しますが、この構成ではそれがリクエストごとに変わるブロックになるため、代わりにブロック5に明示的なブレークポイントを使用してください。

重要なポイント： キャッシュを共有したいリクエスト間でプレフィックスが同一である最後のブロックに cache_control を配置してください。成長する会話では、各ターンで追加されるブロックが20未満である限り、最後のブロックで問題ありません。以前のコンテンツは変化しないため、次のリクエストのルックバックが以前の書き込みを見つけます。末尾が変化するプロンプト（タイムスタンプ、リクエストごとのコンテキスト、受信メッセージ）の場合は、変化するブロックではなく、静的プレフィックスの末尾にブレークポイントを配置してください。

複数のブレークポイントを使用するタイミング

次のような場合、最大4つのキャッシュブレークポイントを定義できます。

• 異なる頻度で変更される異なるセクションをキャッシュする（たとえば、ツールはめったに変更されないが、コンテキストは毎日更新される）
• キャッシュする内容をより細かく制御する
• 成長する会話によってブレークポイントが最後のキャッシュ書き込みから20ブロック以上先に押し出された場合でも、キャッシュヒットを確保する

キャッシュブレークポイントのコストを理解する

キャッシュブレークポイント自体にはコストはかかりません。 料金が発生するのは次の項目のみです。

• キャッシュ書き込み： 新しいコンテンツがキャッシュに書き込まれるとき（5分のTTLの場合、基本入力トークンより25パーセント高い）
• キャッシュ読み取り： キャッシュされたコンテンツが使用されるとき（基本入力トークン価格の10パーセント、モデルごとの例外あり）
• 通常の入力トークン： キャッシュされていないすべてのコンテンツ

cache_control ブレークポイントを追加してもコストは増加しません。実際にキャッシュされ読み取られたコンテンツに基づいて同じ金額を支払います。ブレークポイントは、どのセクションを独立してキャッシュできるかを制御する手段を提供します。

キャッシング戦略と考慮事項

キャッシュの制限

Claude API、Claude Platform on AWS、Claude Models on Google Cloud (Google managed)、および Microsoft Foundry では、キャッシュ可能な最小プロンプト長は次のとおりです。

• Claude Fable 5.2、Claude Mythos 5.2、Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5、Claude Fable 5、Claude Mythos 5、Claude Haiku 5.5 では512トークン
• Claude Mythos Preview と Claude Opus 4.7 では2,048トークン
• Claude Opus 4.6 と Claude Opus 4.5 では4,096トークン
• Claude Opus 4.8、Claude Sonnet 5、Claude Sonnet 4.6、Claude Sonnet 4.5（非推奨）、Claude Opus 4.1（廃止済み、ただし Claude Models on Google Cloud (Google managed) および Bedrock を除く）、Claude Opus 4（廃止済み、ただし Claude Models on Google Cloud (Google managed) を除く）、Claude Sonnet 4（廃止済み、ただし Claude Models on Google Cloud (Google managed) および Bedrock を除く）では1,024トークン
• Claude Haiku 4.5 では4,096トークン

これらの最小値は、各モデルが利用可能なすべてのプラットフォームで適用されます。

これより短いプロンプトは、cache_control でマークされていてもキャッシュできません。このトークン数未満をキャッシュしようとするリクエストはキャッシングなしで処理され、エラーは返されません。プロンプトがキャッシュされたかどうかを確認するには、レスポンスの usage フィールドを確認してください。cache_creation_input_tokens と cache_read_input_tokens の両方が0の場合、プロンプトはキャッシュされていません（最小長の要件を満たしていなかった可能性が高いです）。

プロンプトがモデルとプラットフォームの最小値にわずかに届かない場合は、しきい値に達するまでキャッシュされるコンテンツを拡張する価値があることがよくあります。キャッシュ読み取りはキャッシュされていない入力トークンよりも大幅に安価なため、最小値に達することで、頻繁に再利用されるプロンプトのコストを削減できます。

同時リクエストの場合、キャッシュエントリは最初のレスポンスが開始された後にのみ利用可能になることに注意してください。並列リクエストでキャッシュヒットが必要な場合は、最初のレスポンスを待ってから後続のリクエストを送信してください。

現在、サポートされているキャッシュタイプは ephemeral のみで、デフォルトの有効期間は5分です。

キャッシュできるもの

リクエスト内のほとんどのブロックはキャッシュできます。これには次のものが含まれます。

• ツール：tools 配列内のツール定義
• システムメッセージ：system 配列内のコンテンツブロック
• テキストメッセージ：messages.content 配列内のコンテンツブロック（ユーザーターンとアシスタントターンの両方）
• 画像とドキュメント：messages.content 配列内のコンテンツブロック（ユーザーターン）
• ツール使用とツール結果：messages.content 配列内のコンテンツブロック（ユーザーターンとアシスタントターンの両方）

これらの各要素は、自動的に、または cache_control でマークすることでキャッシュできます。

キャッシュできないもの

ほとんどのリクエストブロックはキャッシュできますが、いくつかの例外があります。

• 思考ブロックは cache_control で直接キャッシュすることはできません。ただし、思考ブロックが以前のアシスタントターンに含まれる場合は、他のコンテンツと一緒にキャッシュされる可能性があります。この方法でキャッシュされた場合、キャッシュから読み取られる際に入力トークンとしてカウントされます。

• サブコンテンツブロック（引用など）自体は直接キャッシュできません。代わりに、トップレベルのブロックをキャッシュしてください。

  引用の場合、引用のソース資料となるトップレベルのドキュメントコンテンツブロックはキャッシュできます。これにより、引用が参照するドキュメントをキャッシュすることで、引用とともにプロンプトキャッシングを効果的に使用できます。

• 空のテキストブロックはキャッシュできません。

キャッシュを無効化する要因

キャッシュされたコンテンツを変更すると、キャッシュの一部またはすべてが無効化される可能性があります。

プロンプトの構成で説明したように、キャッシュは tools → system → messages という階層に従います。各レベルでの変更は、そのレベルとそれ以降のすべてのレベルを無効化します。

次の表は、さまざまな種類の変更によってキャッシュのどの部分が無効化されるかを示しています。✘ はキャッシュが無効化されることを、✓ はキャッシュが有効なままであることを示します。

会話途中でのツール変更をサポートするモデルでは、inline-tools-2026-09-15 ベータヘッダーを使用すると、tools を編集することなく、会話の途中でツールを追加したり、ツールの定義を変更したりできます。定義を会話途中のシステムメッセージ内の tool_addition ブロックで送信し、tools は最初に送信したとおりのままにしてください。キャッシュされたプレフィックスは引き続き一致するため、追加されたメッセージのみが新しい入力として処理されます。唯一の例外は、遅延されていないツールを含まない tools 配列の場合で、この方法で定義された最初のツールは、そのリクエストで1回の完全なキャッシュミスのコストが発生します。メッセージ内でツールを定義するを参照してください。

キャッシュパフォーマンスの追跡

レスポンスの usage 内（ストリーミングの場合は message_start イベント内）にある次の API レスポンスフィールドを使用して、キャッシュパフォーマンスを監視します。

• cache_creation_input_tokens：新しいエントリを作成する際にキャッシュに書き込まれたトークン数
• cache_read_input_tokens：このリクエストでキャッシュから取得されたトークン数
• input_tokens：キャッシュから読み取られず、キャッシュの作成にも使用されなかった入力トークン数（つまり、最後のキャッシュブレークポイントより後のトークン）

思考ブロックを使用したキャッシング

プロンプトキャッシングとともに思考を使用する場合、思考ブロックには特別な動作があります。

他のコンテンツとの自動キャッシング： 思考ブロックは cache_control で明示的にマークすることはできませんが、ツール結果を含む後続の API 呼び出しを行う際に、リクエストコンテンツの一部としてキャッシュされます。これは、会話を続けるために思考ブロックを返すツール使用の際によく発生します。

入力トークンのカウント： 思考ブロックがキャッシュから読み取られると、使用量メトリクスでは入力トークンとしてカウントされます。これはコスト計算とトークン予算の管理において重要です。

キャッシュ無効化のパターン：

• ユーザーメッセージとしてツール結果のみが提供される場合、キャッシュは有効なままです。
• Opus 4.5+、Sonnet 4.6+、Haiku 5.5 では、ツール結果以外のユーザーコンテンツが追加された場合でも思考ブロックはデフォルトで保持されるため、キャッシュは有効なままです。
• それ以前の Opus/Sonnet モデル、および Claude Haiku 4.5 までの Haiku モデルでは、ツール結果以外のユーザーコンテンツが追加されるとキャッシュが無効化され、以前のすべての思考ブロックがコンテキストから取り除かれます。
• このキャッシング動作は、明示的な cache_control マーカーがなくても発生します。

キャッシュの無効化の詳細については、キャッシュを無効化する要因を参照してください。

ツール使用の例：

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)

それ以前の Opus/Sonnet モデル、および Claude Haiku 4.5 までの Haiku モデルでは、この時点で以前のすべての思考ブロックがコンテキストから削除されます。Opus 4.5+、Sonnet 4.6+、Haiku 5.5 では、以前の思考ブロックはデフォルトで保持され、キャッシュされたプレフィックスの一部として残ります。

より詳細な情報については、思考とプロンプトキャッシングを参照してください。

キャッシュの保存と共有

• 組織とワークスペースの分離： キャッシュは組織間で分離されています。異なる組織は、同一のプロンプトを使用していても、キャッシュを共有することはありません。Claude API、Claude Platform on AWS、Microsoft Foundry では、キャッシュは組織内のワークスペースごとにも分離されます。Claude Models on Google Cloud (Google managed) と Bedrock は組織レベルの分離のみを使用します。

• 完全一致： キャッシュヒットには、キャッシュコントロールでマークされたブロックまで（そのブロックを含む）のすべてのテキストと画像を含め、100%同一のプロンプトセグメントが必要です。

• 出力トークンの生成： プロンプトキャッシングは出力トークンの生成には影響しません。受け取るレスポンスは、プロンプトキャッシングを使用しなかった場合とまったく同じです。

効果的なキャッシングのベストプラクティス

プロンプトキャッシングのパフォーマンスを最適化するには：

• マルチターンの会話では自動キャッシングから始めてください。ブレークポイントの管理を自動的に処理します。
• 変更頻度が異なるセクションをキャッシュする必要がある場合は、明示的なブロックレベルのブレークポイントを使用してください。
• システム指示、背景情報、大きなコンテキスト、頻繁に使用されるツール定義など、安定した再利用可能なコンテンツをキャッシュしてください。
• 最高のパフォーマンスを得るには、キャッシュするコンテンツをプロンプトの先頭に配置してください。
• キャッシュブレークポイントを戦略的に使用して、異なるキャッシュ可能なプレフィックスセクションを分離してください。
• リクエスト間で同一のままである最後のブロックにブレークポイントを配置してください。静的なプレフィックスと変化する末尾（タイムスタンプ、リクエストごとのコンテキスト、受信メッセージ）を持つプロンプトの場合、それは変化するブロックではなく、プレフィックスの末尾です。
• キャッシュヒット率を定期的に分析し、必要に応じて戦略を調整してください。

さまざまなユースケースに合わせた最適化

シナリオに合わせてプロンプトキャッシング戦略を調整してください。

• 会話型エージェント：特に長い指示やアップロードされたドキュメントを含む長時間の会話において、コストとレイテンシを削減します。
• コーディングアシスタント：関連するセクションやコードベースの要約版をプロンプト内に保持することで、オートコンプリートやコードベースに関する Q&A を改善します。
• 大規模なドキュメント処理：レスポンスのレイテンシを増やすことなく、画像を含む完全な長文資料をプロンプトに組み込みます。
• 詳細な指示セット：Claude のレスポンスを微調整するために、指示、手順、例の広範なリストを共有します。開発者はプロンプトに1つか2つの例を含めることが多いですが、プロンプトキャッシングを使用すれば、高品質な回答の多様な例を20個以上含めることで、さらに優れたパフォーマンスを得られます。
• エージェント的なツール使用：各ステップで通常新しい API 呼び出しが必要となる、複数のツール呼び出しや反復的なコード変更を伴うシナリオのパフォーマンスを向上させます。
• 書籍、論文、ドキュメント、ポッドキャストの文字起こし、その他の長文コンテンツ：ドキュメント全体をプロンプトに埋め込み、ユーザーが質問できるようにすることで、あらゆるナレッジベースをインタラクティブにします。

よくある問題のトラブルシューティング

予期しない動作が発生した場合：

• キャッシュされるセクションが呼び出し間で同一であることを確認してください。明示的なブレークポイントの場合は、cache_control マーカーが同じ位置にあることを確認してください。
• 呼び出しがキャッシュの有効期間（デフォルトでは5分）内に行われていることを確認してください。
• tool_choice、画像の使用、思考の設定、output_config.effort が呼び出し間で一貫していることを確認してください。
• モデルとプラットフォームの最小トークン数以上をキャッシュしていることを確認してください（キャッシュの制限を参照）。
• ブレークポイントがリクエスト間で同一のままであるブロックにあることを確認してください。キャッシュ書き込みはブレークポイントでのみ発生し、そのブロックが変化する（タイムスタンプ、リクエストごとのコンテキスト、受信メッセージ）と、プレフィックスハッシュは決して一致しません。ルックバックはブレークポイントより前にある安定したコンテンツを見つけるわけではなく、以前のリクエストがそれぞれのブレークポイントで書き込んだエントリのみを見つけます。
• 一部の言語（たとえば Swift、Go）では JSON 変換時にキーの順序がランダム化され、キャッシュが壊れるため、tool_use コンテンツブロック内のキーの順序が安定していることを確認してください。
• キャッシュ診断を使用して、API に連続するリクエストを比較させ、プロンプトのどの部分が分岐したかを報告させてください。

1時間のキャッシュ期間

5分では短すぎる場合、Anthropic は追加料金で1時間のキャッシュ期間も提供しています。

拡張キャッシュを使用するには、次のように cache_control の定義に ttl を含めます。

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

レスポンスには、次のような詳細なキャッシュ情報が含まれます。

{
  "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分のキャッシュを使用してください。

1時間のキャッシュは、次のシナリオで最適に使用されます。

• 5分ごとよりも低い頻度で、かつ1時間ごとよりも高い頻度で使用される可能性が高いプロンプトがある場合。たとえば、エージェント的なサイドエージェントの処理に5分以上かかる場合や、ユーザーとの長いチャット会話を保存していて、そのユーザーが次の5分以内に応答しない可能性が一般的に高いと予想される場合です。
• レイテンシが重要で、後続のプロンプトが5分を超えて送信される可能性がある場合。
• キャッシュヒットはレート制限から差し引かれないため、レート制限の利用効率を改善したい場合。

異なるTTLの混在

同じリクエスト内で1時間と5分のキャッシュ制御の両方を使用できますが、重要な制約があります。TTLが長いキャッシュエントリは、TTLが短いものより前に配置する必要があります（つまり、1時間のキャッシュエントリは、5分のキャッシュエントリより前に配置する必要があります）。

TTLを混在させる場合、Claude APIはプロンプト内の3つの課金位置を決定します。

1. 位置A：プロンプト内の最後のキャッシュヒットにおけるトークン数（ヒットがない場合は0）。
   • 5分のTTLでキャッシュされたエントリへのヒットは、それより後に位置する、TTLが1時間のcache_controlブロックがキャッシュミスである場合、ヒットとはみなされません。
   • 5分のTTLでキャッシュされたエントリを読み取るリクエストは、今回のリクエストで"ttl": "1h"を指定している場合でも、そのエントリの5分の有効期間を最初から開始し直します。
2. 位置B：Aの後にある、TTLが1時間の最後のcache_controlブロックにおけるトークン数（存在しない場合はAと等しい）。
3. 位置C：最後のcache_controlブロックにおけるトークン数。

以下の料金が課金されます。

1. Aに対するキャッシュ読み取りトークン。
2. (B - A)に対する1時間キャッシュ書き込みトークン。
3. (C - B)に対する5分キャッシュ書き込みトークン。

以下に、それぞれキャッシュヒットとキャッシュミスが異なる3つのリクエストの例を示します。ボックスに示されているように、それぞれ異なる料金が計算されます。

キャッシュの事前ウォームアップ

キャッシュの事前ウォームアップ（pre-warming）を使用すると、ユーザーが実際のリクエストをトリガーする前に、システムプロンプトやツール定義をプロンプトキャッシュに読み込むことができます。これにより、最初のユーザーインタラクションにおけるキャッシュミスのレイテンシペナルティを軽減でき、レイテンシが重要なアプリケーションで「time-to-first-token」（最初のトークンまでの時間）、すなわちTTFTを短縮できます。

仕組み

リクエストでmax_tokens: 0を設定します。APIはプロンプトをモデルに読み込み、すべてのcache_controlブレークポイントでキャッシュを書き込んだ後、出力を生成せずに即座に返します。レスポンスには空のcontent配列、stop_reason: "max_tokens"、そして完全に値が設定されたusageブロックが含まれます。

cache_controlブレークポイントは、プレースホルダーのユーザーメッセージではなく、後続のリクエストと共有される最後のブロック（通常はシステムプロンプトまたはツール定義）に配置してください。そうしないと、キャッシュエントリはプレースホルダーをキーとして作成され、後続のリクエストはそれにヒットしません。また、思考の設定とoutput_config.effortも後続のリクエストと同じものを使用してください。これらの値はプロンプトにレンダリングされるため（キャッシュを無効化する要因を参照）、異なる設定で事前ウォームアップを行うと、実際のトラフィックが決してヒットしないエントリが書き込まれる可能性があります。つまり、自動キャッシングではなく明示的なキャッシュブレークポイントを使用することになります。自動キャッシングはブレークポイントを最後のブロックに配置しますが、ここではそれがプレースホルダーになってしまうためです。プレースホルダーのユーザーメッセージには、空白以外の内容を含む任意の文字列を使用できます（ここでの例では"warmup"を使用しています）。その内容はモデルに読み込まれますが、応答されることはありません。

client = anthropic.Anthropic()

# ユーザーが来る前にこれを実行し、共有のシステムプロンプトキャッシュをウォームアップします。
prewarm = client.messages.create(
    model="claude-opus-5-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)  # []
print(prewarm.usage)

APIは空のcontent配列を返します。

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

一般的な使用パターン

アプリケーションの起動時（または定期的な間隔で）事前ウォームアップリクエストを送信し、事前ウォームアップが完了した後に実際のユーザーリクエストを送信します。

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# ユーザーのトラフィックが到着する前にキャッシュをウォームアップします。
prewarm_cache()

# 後でユーザーがメッセージを送信する時点では、システムプロンプトのプレフィックスはすでにキャッシュされています。
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

キャッシュのTTLは引き続き適用されることに注意してください。デフォルトの5分キャッシュの場合、キャッシュをウォームな状態に保つには、少なくとも5分ごとに新しい事前ウォームアップリクエストを送信してください。ユーザーリクエスト間の間隔が長い場合は、代わりに1時間のキャッシュ期間を使用してください。

制限事項

以下のいずれかが設定されている場合、max_tokens: 0リクエストはinvalid_request_errorで拒否されます。これらはいずれも、トークン予算がゼロでは生成できない出力を前提としているためです。

• stream: true
• 拡張思考（thinking.type: "enabled"）
• 構造化出力（output_config.format）
• {"type": "tool", ...}または{"type": "any"}のtool_choice

max_tokens: 0はMessage Batchesリクエスト内でも拒否されます。事前ウォームアップは最初のトークンまでの時間を対象としていますが、これはバッチ処理には当てはまらず、また、バッチ処理中に書き込まれたキャッシュエントリは後続のリクエストが実行される前に期限切れになる可能性が高いためです。

max_tokens=1による回避策の置き換え

一部のアプリケーションは、キャッシュをウォームアップするためにmax_tokens: 1のリクエストを送信しています。リクエストで許可される場合はmax_tokens: 0を優先してください。出力が生成されないため、破棄すべき1トークンの応答がなく、出力トークンも課金されず、リクエストの意図が明確になります。

プロンプトキャッシングの例

プロンプトキャッシングを始めるにあたり、Claude Cookbookのプロンプトキャッシングのレシピで詳細な例とベストプラクティスを確認できます。

以下のコードスニペットは、さまざまなプロンプトキャッシングのパターンを示しています。これらの例では、さまざまなシナリオでキャッシングを実装する方法を示しており、この機能の実際の応用を理解するのに役立ちます。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?",
        }
    ],
)
print(response.usage.model_dump_json())

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": { "timezone": { "type": "string" } },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        # ...これまでの長い会話
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ],
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Good to know."},
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"},
                },
            ],
        },
    ],
)
print(response.usage.model_dump_json())

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"],
            },
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {"type": "string", "description": "Document ID"}
                },
                "required": ["doc_id"],
            },
            "cache_control": {"type": "ephemeral"},
        },
    ],
    system=[
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"},
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                }
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
    ],
)
print(response.usage.model_dump_json())

データ保持

プロンプトキャッシング（自動と明示的の両方）は「zero data retention」（ゼロデータ保持）、すなわちZDRの対象です。Anthropicは、プロンプトやClaudeの応答の生のテキストを保存しません。

キャッシュされたコンテンツのKV（キーバリュー）キャッシュ表現と暗号学的ハッシュはメモリ内にのみ保持され、保存状態（at rest）では保持されません。キャッシュエントリの最小有効期間は5分（標準）または1時間（拡張）で、その後は即時ではないものの速やかに削除されます。キャッシュエントリは組織間で分離されており、Claude API、Claude Platform on AWS、Microsoft Foundryでは、組織内のワークスペース間でも分離されています。

よくある質問

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

client.beta.prompt_caching.messages.create(**params)

client.messages.create(**params)

client.beta.promptCaching.messages.create(/* ... */);

client.messages.create(/* ... */);

利用可能状況