プロンプトキャッシング

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

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

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

最も簡単な開始方法は自動キャッシングです：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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."
      }
    ]
  }'

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

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

プロンプトキャッシングを有効にしてリクエストを送信すると：

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

これは特に以下の場合に役立ちます：

• 多くの例を含むプロンプト
• 大量のコンテキストや背景情報
• 一貫した指示を持つ繰り返しタスク
• 長いマルチターン会話

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

料金

プロンプトキャッシングは新しい料金体系を導入します。以下の表は、サポートされている各モデルの100万トークンあたりの価格を示しています：

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

プロンプトキャッシング（自動および明示的の両方）は現在以下でサポートされています：

• Claude Opus 4.6
• Claude Opus 4.5
• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.6
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7（非推奨）
• Claude Haiku 4.5
• Claude Haiku 3.5（非推奨）
• Claude Haiku 3

自動キャッシング

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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?"}
    ]
  }'

マルチターン会話での自動キャッシングの仕組み

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

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

TTLサポート

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

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

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

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

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

{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [...]
}

変わらないこと

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

エッジケース

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

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

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

プロンプトの構造化

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

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

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

静的コンテンツの末尾に1つのキャッシュブレークポイントを使用するだけで、システムはキャッシュされたブロックの最長一致シーケンスを自動的に見つけます。これがどのように機能するかを理解することで、キャッシング戦略を最適化できます。

3つのコア原則：

1. キャッシュキーは累積的：cache_controlでブロックを明示的にキャッシュする場合、キャッシュハッシュキーは会話内のすべての前のブロックを順番にハッシュすることで生成されます。これは、各ブロックのキャッシュがその前に来たすべてのコンテンツに依存することを意味します。

2. 後方順次チェック：システムは明示的なブレークポイントから後方に向かって作業し、各前のブロックを逆順にチェックすることでキャッシュヒットを確認します。これにより、可能な限り長いキャッシュヒットが得られます。

3. 20ブロックのルックバックウィンドウ：システムは各明示的なcache_controlブレークポイントの前の最大20ブロックのみをチェックします。一致なしで20ブロックをチェックした後、チェックを停止し、次の明示的なブレークポイント（存在する場合）に移動します。

例：ルックバックウィンドウの理解

30のコンテンツブロックを持つ会話で、ブロック30にのみcache_controlを設定した場合を考えます：

• 前のブロックに変更なしでブロック31を送信する場合：システムはブロック30をチェックします（一致！）。ブロック30でキャッシュヒットが得られ、ブロック31のみ処理が必要です。

• ブロック25を変更してブロック31を送信する場合：システムはブロック30 → 29 → 28... → 25（一致なし）→ 24（一致！）と後方にチェックします。ブロック24は変更されていないため、ブロック24でキャッシュヒットが得られ、ブロック25〜30のみ再処理が必要です。

• ブロック5を変更してブロック31を送信する場合：システムはブロック30 → 29 → 28... → 11（チェック#20）と後方にチェックします。一致なしで20回チェックした後、チェックを停止します。ブロック5は20ブロックウィンドウを超えているため、キャッシュヒットは発生せず、すべてのブロックを再処理する必要があります。ただし、ブロック5に明示的なcache_controlブレークポイントを設定していた場合、システムはそのブレークポイントからチェックを続けます：ブロック5（一致なし）→ ブロック4（一致！）。これにより、ブロック4でキャッシュヒットが可能になり、編集可能なコンテンツの前にブレークポイントを配置すべき理由を示しています。

重要なポイント：キャッシュヒットの可能性を最大化するために、常に会話の末尾に明示的なキャッシュブレークポイントを設定してください。また、編集可能なコンテンツブロックの直前にブレークポイントを設定して、それらのセクションを独立してキャッシュできるようにしてください。

複数のブレークポイントを使用する場合

以下の場合に最大4つのキャッシュブレークポイントを定義できます：

• 異なる頻度で変化するセクションをキャッシュする場合（例えば、ツールはほとんど変わらないが、コンテキストは毎日更新される）
• キャッシュされる内容をより細かく制御したい場合
• 最終ブレークポイントの20ブロック以上前のコンテンツのキャッシングを確保する場合
• 20ブロックウィンドウを超えた変更が発生してもキャッシュヒットを保証するために、編集可能なコンテンツの前にブレークポイントを配置する場合

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

キャッシュブレークポイント自体は追加コストを発生させません。 課金されるのは以下のみです：

• キャッシュ書き込み：新しいコンテンツがキャッシュに書き込まれる場合（5分TTLの場合、基本入力トークンより25%多い）
• キャッシュ読み取り：キャッシュされたコンテンツが使用される場合（基本入力トークン価格の10%）
• 通常の入力トークン：キャッシュされていないコンテンツの場合

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

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

キャッシュの制限

キャッシュ可能な最小プロンプト長は：

• Claude Opus 4.6、Claude Opus 4.5の場合：4096トークン
• Claude Sonnet 4.6の場合：2048トークン
• Claude Sonnet 4.5、Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7（非推奨）の場合：1024トークン
• Claude Haiku 4.5の場合：4096トークン
• Claude Haiku 3.5（非推奨）とClaude Haiku 3の場合：2048トークン

短いプロンプトはcache_controlでマークされていてもキャッシュできません。この数より少ないトークンをキャッシュするリクエストはキャッシングなしで処理されます。プロンプトがキャッシュされたかどうかを確認するには、レスポンスの使用状況フィールドを参照してください。

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

現在、「ephemeral」がサポートされている唯一のキャッシュタイプであり、デフォルトで5分の有効期間があります。

キャッシュできるもの

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

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

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

キャッシュできないもの

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

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

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

  引用の場合、引用のソース素材として機能するトップレベルのドキュメントコンテンツブロックをキャッシュできます。これにより、引用が参照するドキュメントをキャッシュすることで、引用と一緒にプロンプトキャッシングを効果的に使用できます。

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

キャッシュを無効にするもの

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

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

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

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

レスポンスのusage内（またはストリーミングの場合はmessage_startイベント内）のこれらのAPIレスポンスフィールドを使用してキャッシュパフォーマンスを監視します：

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

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

thinkingブロックを使用したキャッシング

拡張thinkingをプロンプトキャッシングと一緒に使用する場合、thinkingブロックには特別な動作があります：

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

入力トークンのカウント：thinkingブロックがキャッシュから読み取られると、使用状況メトリクスで入力トークンとしてカウントされます。これはコスト計算とトークンバジェットに重要です。

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

• ツール結果のみがユーザーメッセージとして提供される場合、キャッシュは有効のままです
• 非ツール結果のユーザーコンテンツが追加されると、キャッシュが無効になり、以前のすべてのthinkingブロックが削除されます
• このキャッシュ動作は、明示的なcache_controlマーカーなしでも発生します

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

ツール使用の例：

リクエスト1: ユーザー: "パリの天気は？"
レスポンス: [thinking_block_1] + [tool_use block 1]

リクエスト2:
ユーザー: ["パリの天気は？"],
アシスタント: [thinking_block_1] + [tool_use block 1],
ユーザー: [tool_result_1, cache=True]
レスポンス: [thinking_block_2] + [text block 2]
# リクエスト2はそのリクエストコンテンツをキャッシュします（レスポンスではない）
# キャッシュには：ユーザーメッセージ、thinking_block_1、tool_use block 1、tool_result_1が含まれます

リクエスト3:
ユーザー: ["パリの天気は？"],
アシスタント: [thinking_block_1] + [tool_use block 1],
ユーザー: [tool_result_1, cache=True],
アシスタント: [thinking_block_2] + [text block 2],
ユーザー: [テキストレスポンス, cache=True]
# 非ツール結果のユーザーブロックにより、すべてのthinkingブロックが無視されます
# このリクエストはthinkingブロックが存在しなかったかのように処理されます

非ツール結果のユーザーブロックが含まれると、新しいアシスタントループが指定され、以前のすべてのthinkingブロックがコンテキストから削除されます。

詳細については、拡張thinkingドキュメントを参照してください。

キャッシュストレージと共有

• 組織の分離：キャッシュは組織間で分離されています。異なる組織は、同一のプロンプトを使用していても、キャッシュを共有しません。

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

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

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

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

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

異なるユースケースの最適化

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

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

一般的な問題のトラブルシューティング

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

• キャッシュされたセクションが呼び出し間で同一であることを確認してください。明示的なブレークポイントの場合、cache_controlマーカーが同じ場所にあることを確認してください
• 呼び出しがキャッシュの有効期間内（デフォルトで5分）に行われていることを確認してください
• tool_choiceと画像の使用が呼び出し間で一貫していることを確認してください
• 最小トークン数以上をキャッシュしていることを確認してください
• システムは以前のコンテンツブロック境界（ブレークポイントの前の最大約20ブロック）でキャッシュヒットを自動的にチェックします。20以上のコンテンツブロックを持つプロンプトの場合、すべてのコンテンツをキャッシュできるようにするために、プロンプトの早い段階で追加のcache_controlパラメータが必要になる場合があります
• tool_useコンテンツブロックのキーが安定した順序を持っていることを確認してください。一部の言語（例えば、Swift、Go）はJSON変換中にキーの順序をランダム化し、キャッシュを壊します

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": 456,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

現在のcache_creation_input_tokensフィールドはcache_creationオブジェクト内の値の合計と等しいことに注意してください。

1時間キャッシュを使用する場合

定期的なペースで使用されるプロンプト（つまり、5分ごとより頻繁に使用されるシステムプロンプト）がある場合は、引き続き5分キャッシュを使用してください。追加料金なしで更新され続けます。

1時間キャッシュは以下のシナリオで最も効果的です：

• 5分より少ない頻度で使用される可能性が高いが、1時間ごとより頻繁に使用されるプロンプトがある場合。例えば、エージェントのサイドエージェントが5分以上かかる場合や、ユーザーとの長いチャット会話を保存していて、そのユーザーが次の5分以内に応答しない可能性がある場合。
• レイテンシが重要で、フォローアッププロンプトが5分を超えて送信される可能性がある場合。
• キャッシュヒットはレート制限に対してカウントされないため、レート制限の使用率を改善したい場合。

異なるTTLの混在

同じリクエストで1時間と5分のキャッシュコントロールの両方を使用できますが、重要な制約があります：TTLが長いキャッシュエントリは短いTTLの前に表示される必要があります（つまり、1時間のキャッシュエントリは5分のキャッシュエントリの前に表示される必要があります）。

TTLを混在させる場合、プロンプト内の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つのリクエストの入力トークンを示しており、それぞれ異なるキャッシュヒットとキャッシュミスがあります。それぞれ異なる計算された料金があり、結果として色付きのボックスに示されています。

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

プロンプトキャッシングを始めるにあたり、詳細な例とベストプラクティスを含むプロンプトキャッシングクックブックを用意しています。

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

データ保持

プロンプトキャッシングは、キャッシュされたコンテンツのKV（キーバリュー）キャッシュ表現と暗号ハッシュを保存しますが、プロンプトや応答の生テキストは保存しません。キャッシュエントリの最小有効期間は5分（標準）または60分（拡張）です。キャッシュエントリは組織間で分離されています。Anthropicは生のプロンプトや応答テキストを保存しないため、この機能はZDR型のデータ保持コミットメントを必要とするお客様に適している場合があります。

すべての機能にわたるZDR適格性については、APIとデータ保持をご覧ください。

FAQ