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

以下は、cache_controlブロックを使用してMessages APIでプロンプトキャッシングを実装する例です：

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-20250514",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input
JSON
{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

この例では、「高慢と偏見」の全文がcache_controlパラメータを使用してキャッシュされています。これにより、この大きなテキストを複数のAPI呼び出しで再利用でき、毎回再処理する必要がなくなります。ユーザーメッセージのみを変更することで、キャッシュされたコンテンツを活用しながら本に関するさまざまな質問をすることができ、より速いレスポンスと効率性の向上につながります。

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

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

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

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

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

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

プロンプトキャッシングはプレフィックス全体をキャッシュします

プロンプトキャッシングは、プロンプト全体 - tools、system、およびmessages（この順序で）を、cache_controlで指定されたブロックまで含めて参照します。

​
価格設定

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

ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
Claude Opus 4$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.7$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.5$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Haiku 3.5$0.80 / MTok$1 / MTok$1.6 / MTok$0.08 / MTok$4 / MTok
Claude Opus 3$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Haiku 3$0.25 / MTok$0.30 / MTok$0.50 / MTok$0.03 / MTok$1.25 / MTok

注意：

  • 5分間のキャッシュ書き込みトークンは、基本入力トークン価格の1.25倍
  • 1時間のキャッシュ書き込みトークンは、基本入力トークン価格の2倍
  • キャッシュ読み取りトークンは、基本入力トークン価格の0.1倍
  • 通常の入力および出力トークンは標準料金で価格設定されています

​
プロンプトキャッシングの実装方法

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

プロンプトキャッシングは現在、以下のモデルでサポートされています：

  • Claude Opus 4
  • Claude Sonnet 4
  • Claude Sonnet 3.7
  • Claude Sonnet 3.5
  • Claude Haiku 3.5
  • Claude Haiku 3
  • Claude Opus 3

​
プロンプトの構造化

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

キャッシュプレフィックスは次の順序で作成されます：tools、system、そしてmessages。

cache_controlパラメータを使用して、最大4つのキャッシュブレークポイントを定義でき、異なる再利用可能なセクションを別々にキャッシュすることができます。各ブレークポイントでは、システムは自動的に前の位置でのキャッシュヒットを確認し、見つかった場合は最も長い一致するプレフィックスを使用します。

​
キャッシュの制限

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

  • Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5、Claude Opus 3では1024トークン
  • Claude Haiku 3.5とClaude Haiku 3では2048トークン

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

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

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

​
キャッシュ可能なもの

リクエスト内のほとんどのブロックはcache_controlでキャッシング用に指定できます。これには以下が含まれます：

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

これらの要素はそれぞれcache_controlでマークして、リクエストのその部分のキャッシングを有効にすることができます。

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

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

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

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

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

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

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

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

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

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

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

  • システム指示、背景情報、大きなコンテキスト、または頻繁なツール定義など、安定した再利用可能なコンテンツをキャッシュします。
  • 最高のパフォーマンスを得るために、キャッシュされたコンテンツをプロンプトの先頭に配置します。
  • 異なるキャッシュ可能なプレフィックスセクションを分離するために、キャッシュブレークポイントを戦略的に使用します。
  • キャッシュヒット率を定期的に分析し、必要に応じて戦略を調整します。

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

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

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

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

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

  • キャッシュされたセクションが同一であり、呼び出し間で同じ場所にcache_controlでマークされていることを確認します
  • 呼び出しがキャッシュの有効期間内（デフォルトでは5分）に行われていることを確認します
  • 呼び出し間でtool_choiceと画像の使用が一貫していることを確認します
  • 少なくとも最小数のトークンをキャッシュしていることを確認します
  • システムはキャッシュブレークポイント前の位置で以前にキャッシュされたコンテンツを使用しようとしますが、プロンプトの前の部分でのキャッシュルックアップを保証するために追加のcache_controlパラメータを使用することができます。これは、非常に長いコンテンツブロックのリストを持つクエリに役立つ場合があります

プロンプトのどこかでのtool_choiceの変更や画像の有無の変更はキャッシュを無効にし、新しいキャッシュエントリを作成する必要があることに注意してください。

​
思考ブロックを使ったキャッシング

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

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

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

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

  • ツール結果のみがユーザーメッセージとして提供される場合、キャッシュは有効なままです
  • ツール結果以外のユーザーコンテンツが追加されると、キャッシュは無効になり、以前のすべての思考ブロックが削除されます
  • このキャッシング動作は、明示的な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]
# ツール結果以外のユーザーブロックがあると、すべての思考ブロックが無視されます
# このリクエストは思考ブロックが存在しなかったかのように処理されます

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

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

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

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

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

  • 出力トークン生成：プロンプトキャッシングは出力トークン生成に影響を与えません。受け取るレスポンスは、プロンプトキャッシングが使用されていない場合と同じになります。

​
1時間キャッシュ期間（ベータ）

5分が短すぎると感じる場合、Anthropicは1時間のキャッシュ期間も提供しています。

拡張キャッシュを使用するには、リクエストにベータヘッダーとしてextended-cache-ttl-2025-04-11を追加し、次のようにcache_control定義にttlを含めます：

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

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

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "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分を超えて送信される可能性がある場合。
  • キャッシュヒットはレート制限から差し引かれないため、レート制限の利用率を向上させたい場合。

5分と1時間のキャッシュはレイテンシーに関して同じように動作します。一般的に、長いドキュメントでは最初のトークンまでの時間が改善されます。

​
異なるTTLの混在

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

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

  1. 位置A：最高のキャッシュヒット（またはヒットがない場合は0）でのトークン数。
  2. 位置B：Aの後の最高の1時間cache_controlブロックでのトークン数（存在しない場合はAに等しい）。
  3. 位置C：最後のcache_controlブロックでのトークン数。

Aが最高のキャッシュヒットであるため、Bおよび/またはCがAより大きい場合、それらは必然的にキャッシュミスになります。

以下に対して課金されます：

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

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

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

プロンプトキャッシングを始めるのに役立つように、詳細な例とベストプラクティスを含むプロンプトキャッシングクックブックを用意しました。

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

​
FAQ