プロンプトキャッシング

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

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

• 自動キャッシング：リクエストのトップレベルにcache_controlフィールドを1つ追加します。システムは「cache breakpoint」（キャッシュブレークポイント）を最後のキャッシュ可能なブロックに自動的に適用し、会話が長くなるにつれてそれを前方に移動させます。増え続けるメッセージ履歴を自動的にキャッシュしたいマルチターン会話に最適です。
• 明示的なキャッシュブレークポイント：個々のコンテンツブロックに直接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万トークンあたりの価格を示しています。

Model	Base tokens		Prompt caching
Name	Input	Output	5m writes	1h writes	Hits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / 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 5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / MTok
Additional models
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 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 3.5	$0.80 / MTok	$4 / MTok	$1 / MTok	$1.60 / MTok	$0.08 / MTok

^{1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.}

^{2 Cache hits and refreshes on Claude Opus 5.5 are priced at 0.05x the base input price.}

^{All other models use the standard 0.1x multiplier.}

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

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

自動キャッシング

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

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分の「time to live」（有効期間）、すなわち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ブロックの「lookback window」（ルックバックウィンドウ）は、すべて明示的なブレークポイントの場合と同様に適用されます。

エッジケース

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

例：増え続ける会話におけるルックバック

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

• ターン1： 10ブロック、ブレークポイントはブロック10。以前のキャッシュエントリは存在しません。システムはブロック10にエントリを書き込みます。
• ターン2： 15ブロック、ブレークポイントはブロック15。ブロック15にはエントリがないため、システムはブロック10まで遡り、ターン1のエントリを見つけます。ブロック10で「cache hit」（キャッシュヒット）となり、システムはブロック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%、Claude Fable 5.1およびClaude Mythos 5.1では2.5%、Claude Opus 5.5では5%）
• 通常の入力トークン： キャッシュされていないすべてのコンテンツ

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

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

キャッシュの制限

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

• Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Fable 5、Claude Mythos 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（BedrockおよびGoogle Cloudを除き廃止済み）、Claude Opus 4（Google Cloudを除き廃止済み）、Claude Sonnet 4（BedrockおよびGoogle Cloudを除き廃止済み）では1,024トークン
• Claude Haiku 4.5では4,096トークン
• Claude Haiku 3.5（BedrockおよびGoogle Cloudを除き廃止済み）では2,048トークン

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

これより短いプロンプトは、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以降では、ツール結果以外のユーザーコンテンツが追加された場合でも思考ブロックはデフォルトで保持されるため、キャッシュは有効なままです
• それ以前のOpus/Sonnetモデルおよびすべての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]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

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

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

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

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

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

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

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

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

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

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

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

• 会話型エージェント：長い会話、特に長い指示やアップロードされたドキュメントを含む会話のコストと「latency」（レイテンシ）を削減します。
• コーディングアシスタント：関連するセクションやコードベースの要約版をプロンプトに保持することで、オートコンプリートやコードベースに関する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分のキャッシュを使用してください。5分のキャッシュは追加料金なしで更新され続けるためです。

1時間のキャッシュは、次のようなシナリオで最も効果的に使用できます：

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

異なるTTLの混在

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

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

1. 位置 A：最も後方のキャッシュヒットにおけるトークン数（ヒットがない場合は0）。
2. 位置 B：A より後にある最も後方の1時間の cache_control ブロックにおけるトークン数（存在しない場合は A と等しい）。
3. 位置 C：最後の cache_control ブロックにおけるトークン数。

次の項目に対して課金されます。

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

以下に3つの例を示します。これは3つのリクエストの入力トークンを表しており、それぞれ異なるキャッシュヒットとキャッシュミスがあります。その結果、それぞれ異なる料金が計算され、色付きのボックスに示されています。

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

「cache pre-warming」（キャッシュの事前ウォームアップ）を使用すると、ユーザーが実際のリクエストを送信する前に、システムプロンプトやツール定義をプロンプトキャッシングのキャッシュに読み込んでおくことができます。これにより、最初のユーザーインタラクションで発生する「cache miss」（キャッシュミス）による「latency」（レイテンシ）のペナルティがなくなります。その結果、レイテンシが重要なアプリケーションにおいて、「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

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

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

max_tokens: 0が利用可能になる前は、一部のアプリケーションがmax_tokens: 1のウォームアップ呼び出しで同じ効果を得ていました。現在はmax_tokens: 0のアプローチが推奨されます。出力が生成されないため、破棄すべき1トークンの応答がなく、出力トークンも課金されず、リクエストの意図も明確になります。

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

プロンプトキャッシングを始めるにあたって、プロンプトキャッシングのクックブックに詳細な例とベストプラクティスが掲載されています。

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

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の応答の生テキストを保存しません。

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

すべての機能のZDR対象状況については、APIとデータ保持を参照してください。

よくある質問

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(/* ... */);