プロンプトキャッシングは、プロンプト内の特定のプレフィックスから再開することで、API使用を最適化する強力な機能です。このアプローチにより、反復的なタスクや一貫した要素を持つプロンプトの処理時間とコストが大幅に削減されます。 Messages APIで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-sonnet-4-5",  "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."  }  ]  }'  # キャッシュチェックポイントまで同じ入力でモデルを再度呼び出す 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分です。キャッシュされたコンテンツが使用されるたびに、キャッシュは追加コストなしで更新されます。
5分が短すぎる場合、Anthropicは追加コストで1時間のキャッシュ期間も提供しています。1時間キャッシュは現在ベータ版です。詳細については、1時間キャッシュ期間を参照してください。
プロンプトキャッシングは完全なプレフィックスをキャッシュしますプロンプトキャッシングは、完全なプロンプト(toolssystemmessagesの順)を参照し、cache_controlで指定されたブロックまでを含みます。

価格設定

プロンプトキャッシングは新しい価格設定構造を導入しています。以下の表は、サポートされている各モデルのトークンあたりの価格を示しています:
ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
Claude Opus 4.1$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Opus 4$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4.5$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.7 (deprecated)$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Haiku 4.5$1 / MTok$1.25 / MTok$2 / MTok$0.10 / MTok$5 / MTok
Claude Haiku 3.5$0.80 / MTok$1 / MTok$1.6 / MTok$0.08 / MTok$4 / MTok
Claude Opus 3 (deprecated)$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.1
  • Claude Opus 4
  • Claude Sonnet 4.5
  • Claude Sonnet 4
  • Claude Sonnet 3.7
  • Claude Haiku 4.5
  • Claude Haiku 3.5
  • Claude Haiku 3
  • Claude Opus 3 (非推奨)

プロンプトの構造化

静的コンテンツ(ツール定義、システム指示、コンテキスト、例)をプロンプトの最初に配置します。cache_controlパラメータを使用して、キャッシング用の再利用可能なコンテンツの終了をマークします。 キャッシュプレフィックスは次の順序で作成されます:toolssystemmessages。この順序は、各レベルが前のレベルに基づいて構築される階層を形成します。

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

静的コンテンツの終了時に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ブロックウィンドウを超えた変更が発生した場合でもキャッシュヒットを保証したい場合
重要な制限:プロンプトにキャッシュブレークポイントの前に20個以上のコンテンツブロックがあり、それより前のコンテンツを変更する場合、そのコンテンツの近くに追加の明示的なブレークポイントを追加しない限り、キャッシュヒットは得られません。

キャッシュの制限

最小キャッシュ可能プロンプト長は以下の通りです:
  • Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4.5、Claude Sonnet 4、Claude Sonnet 3.7(非推奨)、Claude Opus 3(非推奨)の場合は1024トークン
  • Claude Haiku 4.5の場合は4096トークン
  • Claude Haiku 3.5およびClaude Haiku 3の場合は2048トークン
より短いプロンプトは、cache_controlでマークされていても、キャッシュできません。このトークン数より少ないトークンをキャッシュするリクエストは、キャッシングなしで処理されます。プロンプトがキャッシュされたかどうかを確認するには、応答使用フィールドを参照してください。 同時リクエストの場合、キャッシュエントリは最初の応答が開始された後にのみ利用可能になることに注意してください。並列リクエストのキャッシュヒットが必要な場合は、最初の応答を待ってから後続のリクエストを送信してください。 現在、「ephemeral」は唯一サポートされているキャッシュタイプであり、デフォルトでは5分の有効期限があります。

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

キャッシュブレークポイント自体はコストを追加しません。 以下の場合にのみ課金されます:
  • キャッシュ書き込み:新しいコンテンツがキャッシュに書き込まれる場合(5分TTLの場合、基本入力トークンより25%多い)
  • キャッシュ読み取り:キャッシュされたコンテンツが使用される場合(基本入力トークン価格の10%)
  • 通常の入力トークン:キャッシュされていないコンテンツの場合
より多くのcache_controlブレークポイントを追加しても、コストは増加しません。実際にキャッシュされて読み取られるコンテンツに基づいて同じ金額を支払います。ブレークポイントは、どのセクションを独立してキャッシュできるかを制御するだけです。

キャッシュできるもの

リクエスト内のほとんどのブロックは、cache_controlでキャッシング用に指定できます。これには以下が含まれます:
  • ツール:tools配列内のツール定義
  • システムメッセージ:system配列内のコンテンツブロック
  • テキストメッセージ:messages.content配列内のコンテンツブロック(ユーターンとアシスタントターンの両方)
  • 画像とドキュメント:ユーターンのmessages.content配列内のコンテンツブロック
  • ツール使用とツール結果:messages.content配列内のコンテンツブロック(ユーターンとアシスタントターンの両方)
これらの各要素は、cache_controlでマークしてそのリクエスト部分のキャッシングを有効にできます。

キャッシュできないもの

ほとんどのリクエストブロックはキャッシュできますが、いくつかの例外があります:
  • 思考ブロックはcache_controlで直接キャッシュできません。ただし、思考ブロックは前のアシスタントターンに表示される場合、他のコンテンツと一緒にキャッシュできます。この方法でキャッシュされる場合、キャッシュから読み取られるときは入力トークンとしてカウントされます。
  • サブコンテンツブロック(引用など)自体は直接キャッシュできません。代わりに、トップレベルブロックをキャッシュしてください。 引用の場合、引用のソース資料として機能するトップレベルドキュメントコンテンツブロックはキャッシュできます。これにより、引用がキャッシュされるドキュメントをキャッシュすることで、プロンプトキャッシングを引用と共に効果的に使用できます。
  • 空のテキストブロックはキャッシュできません。

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

キャッシュされたコンテンツへの変更は、キャッシュの一部またはすべてを無効にする可能性があります。 プロンプトの構造化で説明されているように、キャッシュは階層に従います:toolssystemmessages。各レベルでの変更は、そのレベルとすべての後続レベルを無効にします。 以下の表は、異なるタイプの変更によってキャッシュのどの部分が無効になるかを示しています。✘はキャッシュが無効になることを示し、✓はキャッシュが有効なままであることを示します。
変更内容ツールキャッシュシステムキャッシュメッセージキャッシュ影響
ツール定義ツール定義(名前、説明、パラメータ)を変更すると、キャッシュ全体が無効になります
ウェブ検索トグルウェブ検索を有効/無効にするとシステムプロンプトが変更されます
引用トグル引用を有効/無効にするとシステムプロンプトが変更されます
ツール選択tool_choiceパラメータへの変更はメッセージブロックのみに影響します
画像プロンプト内のどこかに画像を追加/削除するとメッセージブロックに影響します
思考パラメータ拡張思考設定(有効/無効、予算)への変更はメッセージブロックに影響します
拡張思考リクエストに渡される非ツール結果拡張思考が有効な場合、非ツール結果がリクエストで渡されると、以前にキャッシュされたすべての思考ブロックはコンテキストから削除され、それらの思考ブロックに続くコンテキスト内のメッセージはキャッシュから削除されます。詳細については、思考ブロックを使用したキャッシングを参照してください。

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

これらのAPIレスポンスフィールドを使用してキャッシュパフォーマンスを監視します。レスポンス内のusage内(またはストリーミングの場合はmessage_startイベント):
  • cache_creation_input_tokens:新しいエントリを作成するときにキャッシュに書き込まれたトークン数。
  • cache_read_input_tokens:このリクエストのためにキャッシュから取得されたトークン数。
  • input_tokens:キャッシュから読み取られたり、キャッシュを作成するために使用されなかった入力トークン数。

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

プロンプトキャッシングパフォーマンスを最適化するには:
  • システム指示、背景情報、大規模なコンテキスト、または頻繁なツール定義などの安定した再利用可能なコンテンツをキャッシュします。
  • キャッシュされたコンテンツをプロンプトの最初に配置して、最高のパフォーマンスを実現します。
  • キャッシュブレークポイントを戦略的に使用して、異なるキャッシュ可能なプレフィックスセクションを分離します。
  • キャッシュヒット率を最大化するために、会話の終了時と編集可能なコンテンツの直前にキャッシュブレークポイントを設定します。特に20個以上のコンテンツブロックを持つプロンプトを操作する場合に重要です。
  • キャッシュヒット率を定期的に分析し、必要に応じて戦略を調整します。

異なるユースケースに対する最適化

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

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

予期しない動作が発生している場合:
  • キャッシュされたセクションが同一であり、呼び出し全体で同じ場所にcache_controlでマークされていることを確認します
  • 呼び出しがキャッシュ有効期限内(デフォルトでは5分)に行われていることを確認します
  • tool_choiceと画像の使用が呼び出し間で一貫していることを確認します
  • 最小トークン数をキャッシュしていることを確認します
  • システムは自動的に前のコンテンツブロック境界でキャッシュヒットをチェックします(ブレークポイントの前の約20ブロック)。20個以上のコンテンツブロックを持つプロンプトの場合、すべてのコンテンツをキャッシュできるようにするために、プロンプトの前の方に追加のcache_controlパラメータが必要な場合があります
  • tool_useコンテンツブロック内のキーが安定した順序を持つことを確認します。一部の言語(例:Swift、Go)はJSON変換中にキー順序をランダム化し、キャッシュを破壊します
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] # 非ツール結果ユーザーブロックは新しいアシスタントループを指定します # このリクエストは思考ブロックが存在しなかったかのように処理されます 
非ツール結果ユーザーブロックが含まれる場合、新しいアシスタントループが指定され、すべての前の思考ブロックはコンテキストから削除されます。 詳細については、拡張思考ドキュメントを参照してください。

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

  • 組織の分離:キャッシュは組織間で分離されます。異なる組織は、同一のプロンプトを使用していても、キャッシュを共有することはありません。
  • 完全一致:キャッシュヒットには、キャッシュコントロールでマークされたブロックまでを含む、すべてのテキストと画像を含む100%同一のプロンプトセグメントが必要です。
  • 出力トークン生成:プロンプトキャッシングは出力トークン生成に影響しません。受け取る応答は、プロンプトキャッシングが使用されていない場合に得られるものと同一です。

1時間キャッシュ期間

5分が短すぎる場合、Anthropicは追加コストで1時間のキャッシュ期間も提供しています。 拡張キャッシュを使用するには、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分ごとに1回以上の頻度で使用されるシステムプロンプト)がある場合は、5分キャッシュを引き続き使用してください。これは追加料金なしで継続的に更新されるためです。 1時間キャッシュは以下のシナリオで最適に使用されます:
  • 5分より少ない頻度で使用されるが、1時間より多い頻度で使用される可能性があるプロンプトがある場合。例えば、エージェンティックサイドエージェントが5分以上かかる場合、またはユーザーとの長いチャット会話を保存し、一般的にそのユーザーが次の5分以内に応答しないと予想される場合。
  • レイテンシが重要で、フォローアッププロンプトが5分を超えて送信される可能性がある場合。
  • レート制限の利用を改善したい場合。キャッシュヒットはレート制限に対して差し引かれません。
5分キャッシュと1時間キャッシュは遅延に関して同じように動作します。通常、長いドキュメントの場合、最初のトークンまでの時間が改善されます。

異なるTTLの混合

同じリクエストで1時間キャッシュと5分キャッシュコントロールの両方を使用できますが、重要な制約があります:より長いTTLを持つキャッシュエントリは、より短いTTLの前に表示される必要があります(つまり、1時間キャッシュエントリは5分キャッシュエントリの前に表示される必要があります)。 TTLを混合する場合、プロンプト内の3つの請求位置を決定します:
  1. 位置A:最高のキャッシュヒットでのトークンカウント(ヒットがない場合は0)。
  2. 位置BAの後の最高の1時間cache_controlブロックでのトークンカウント(存在しない場合はAに等しい)。
  3. 位置C:最後のcache_controlブロックでのトークンカウント。
Bおよび/またはCAより大きい場合、Aが最高のキャッシュヒットであるため、必然的にキャッシュミスになります。
以下の場合に課金されます:
  1. 位置Aのキャッシュ読み取りトークン。
  2. 位置(B - A)の1時間キャッシュ書き込みトークン。
  3. 位置(C - B)の5分キャッシュ書き込みトークン。
以下は3つの例です。これは3つのリクエストの入力トークンを示し、それぞれが異なるキャッシュヒットとキャッシュミスを持っています。各結果の計算された価格は、色付きボックスに示されています。 TTLの混合図

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

プロンプトキャッシングを開始するのに役立つように、詳細な例とベストプラクティスを含むプロンプトキャッシングクックブックを準備しました。 以下に、さまざまなプロンプトキャッシングパターンを紹介するいくつかのコードスニペットを含めました。これらの例は、異なるシナリオでキャッシングを実装する方法を示し、この機能の実用的なアプリケーションを理解するのに役立ちます:
curl https://api.anthropic.com/v1/messages \  --header "x-api-key: $ANTHROPIC_API_KEY" \  --header "anthropic-version: 2023-06-01" \  --header "content-type: application/json" \  --data \ '{  "model": "claude-sonnet-4-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?"  }  ] }' 
この例は、基本的なプロンプトキャッシング使用法を示し、法的契約の完全なテキストをプレフィックスとしてキャッシュしながら、ユーザー指示をキャッシュしないままにします。最初のリクエストの場合:
  • input_tokens:ユーザーメッセージのみのトークン数
  • cache_creation_input_tokens:法的ドキュメントを含むシステムメッセージ全体のトークン数
  • cache_read_input_tokens:0(最初のリクエストではキャッシュヒットなし)
キャッシュ有効期限内の後続リクエストの場合:
  • input_tokens:ユーザーメッセージのみのトークン数
  • cache_creation_input_tokens:0(新しいキャッシュ作成なし)
  • cache_read_input_tokens:キャッシュされたシステムメッセージ全体のトークン数
curl https://api.anthropic.com/v1/messages \  --header "x-api-key: $ANTHROPIC_API_KEY" \  --header "anthropic-version: 2023-06-01" \  --header "content-type: application/json" \  --data \ '{  "model": "claude-sonnet-4-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",  "description": "The city and state, e.g. San Francisco, CA"  },  "unit": {  "type": "string",  "enum": ["celsius", "fahrenheit"],  "description": "The unit of temperature, either celsius or fahrenheit"  }  },  "required": ["location"]  }  },  # many more tools  {  "name": "get_time",  "description": "Get the current time in a given time zone",  "input_schema": {  "type": "object",  "properties": {  "timezone": {  "type": "string",  "description": "The IANA time zone name, e.g. America/Los_Angeles"  }  },  "required": ["timezone"]  },  "cache_control": {"type": "ephemeral"}  }  ],  "messages": [  {  "role": "user",  "content": "What is the weather and time in New York?"  }  ] }' 
この例では、ツール定義のキャッシングを示します。cache_controlパラメータは最後のツール(get_time)に配置され、すべてのツールを静的プレフィックスの一部として指定します。これは、get_weatherget_timeの前に定義されたその他のツールを含むすべてのツール定義が、単一のプレフィックスとしてキャッシュされることを意味します。このアプローチは、複数のリクエスト全体で再利用したい一貫したツールセットがある場合に役立ちます。毎回再処理することなく。最初のリクエストの場合:
  • input_tokens:ユーザーメッセージのトークン数
  • cache_creation_input_tokens:すべてのツール定義とシステムプロンプトのトークン数
  • cache_read_input_tokens:0(最初のリクエストではキャッシュヒットなし)
キャッシュ有効期限内の後続リクエストの場合:
  • input_tokens:ユーザーメッセージのトークン数
  • cache_creation_input_tokens:0(新しいキャッシュ作成なし)
  • cache_read_input_tokens:すべてのキャッシュされたツール定義とシステムプロンプトのトークン数
curl https://api.anthropic.com/v1/messages \  --header "x-api-key: $ANTHROPIC_API_KEY" \  --header "anthropic-version: 2023-06-01" \  --header "content-type: application/json" \  --data \ '{  "model": "claude-sonnet-4-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 would 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"}  }  ]  }  ] }' 
この例では、マルチターン会話でプロンプトキャッシングを使用する方法を示します。各ターンの間に、最後のメッセージの最後のブロックをcache_controlでマークして、会話を段階的にキャッシュできるようにします。システムは自動的に最長の以前にキャッシュされたプレフィックスをルックアップして使用します。つまり、以前にcache_controlブロックでマークされたブロックは、後でマークされていませんが、5分以内にヒットした場合でも、キャッシュヒット(およびキャッシュリフレッシュ!)と見なされます。さらに、cache_controlパラメータはシステムメッセージに配置されることに注意してください。これは、キャッシュから削除された場合(5分以上使用されない場合)、次のリクエストでキャッシュに追加されるようにするためです。このアプローチは、同じ情報を繰り返し処理することなく、進行中の会話でコンテキストを維持するのに役立ちます。これが正しく設定されている場合、各リクエストのレスポンスの使用で以下が表示されます:
  • input_tokens:新しいユーザーメッセージのトークン数(最小限になります)
  • cache_creation_input_tokens:新しいアシスタントとユーザーターンのトークン数
  • cache_read_input_tokens:前のターンまでの会話のトークン数
curl https://api.anthropic.com/v1/messages \  --header "x-api-key: $ANTHROPIC_API_KEY" \  --header "anthropic-version: 2023-06-01" \  --header "content-type: application/json" \  --data \ '{  "model": "claude-sonnet-4-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"}  }  ]  }  ] }' 
この包括的な例は、プロンプトの異なる部分を最適化するために、利用可能な4つのキャッシュブレークポイントをすべて使用する方法を示しています:
  1. ツールキャッシュ(キャッシュブレークポイント1):最後のツール定義のcache_controlパラメータは、すべてのツール定義をキャッシュします。
  2. 再利用可能な指示キャッシュ(キャッシュブレークポイント2):システムプロンプト内の静的指示は、別々にキャッシュされます。これらの指示はリクエスト間でめったに変更されません。
  3. RAGコンテキストキャッシュ(キャッシュブレークポイント3):ナレッジベースドキュメントは独立してキャッシュされ、ツールと指示を無効にすることなくRAGドキュメントを更新できます。
  4. 会話履歴キャッシュ(キャッシュブレークポイント4):アシスタントの応答はcache_controlでマークされ、会話が進むにつれて会話の段階的なキャッシングを有効にします。
このアプローチは最大の柔軟性を提供します:
  • 最後のユーザーメッセージのみを更新する場合、4つのキャッシュセグメントすべてが再利用されます
  • RAGドキュメントを更新しても同じツールと指示を保つ場合、最初の2つのキャッシュセグメントが再利用されます
  • 会話を変更しても同じツール、指示、ドキュメントを保つ場合、最初の3つのセグメントが再利用されます
  • 各キャッシュブレークポイントは、アプリケーションで何が変更されるかに基づいて独立して無効にできます
最初のリクエストの場合:
  • input_tokens:最後のユーザーメッセージのトークン数
  • cache_creation_input_tokens:すべてのキャッシュされたセグメント(ツール+指示+RAGドキュメント+会話履歴)のトークン数
  • cache_read_input_tokens:0(キャッシュヒットなし)
新しいユーザーメッセージのみの後続リクエストの場合:
  • input_tokens:新しいユーザーメッセージのみのトークン数
  • cache_creation_input_tokens:会話履歴に追加された新しいトークン
  • cache_read_input_tokens:すべての以前にキャッシュされたトークン(ツール+指示+RAGドキュメント+前の会話)
このパターンは特に以下に強力です:
  • 大規模なドキュメントコンテキストを持つRAGアプリケーション
  • 複数のツールを使用するエージェントシステム
  • コンテキストを維持する必要がある長時間実行される会話
  • プロンプトの異なる部分を独立して最適化する必要があるアプリケーション

FAQ

ほとんどの場合、静的コンテンツの終了時に1つのキャッシュブレークポイントで十分です。 システムは自動的にすべての前のコンテンツブロック境界でキャッシュヒットをチェックし(ブレークポイントの前の最大20ブロック)、最長の一致するプレフィックスを使用します。複数のブレークポイントが必要な場合は以下の場合のみです:
  • 目的のキャッシュポイントの前に20個以上のコンテンツブロックがある場合
  • 異なる頻度で更新されるセクションを独立してキャッシュしたい場合
  • コスト最適化のためにキャッシュされるものを明示的に制御したい場合
例:システム指示(めったに変更されない)とRAGコンテキスト(毎日変更される)がある場合、2つのブレークポイントを使用して独立してキャッシュできます。
いいえ、キャッシュブレークポイント自体は無料です。以下の場合にのみ課金されます:
  • キャッシュにコンテンツを書き込む場合(5分TTLの場合、基本入力トークンより25%多い)
  • キャッシュから読み取る場合(基本入力トークン価格の10%)
  • キャッシュされていないコンテンツの通常の入力トークン
ブレークポイントの数は価格に影響しません。実際にキャッシュされて読み取られるコンテンツの量のみが重要です。
キャッシュのデフォルト最小有効期限(TTL)は5分です。この有効期限は、キャッシュされたコンテンツが使用されるたびに更新されます。5分が短すぎる場合、Anthropicは1時間キャッシュTTLも提供しています。
プロンプトで最大4つのキャッシュブレークポイント(cache_controlパラメータを使用)を定義できます。
いいえ、プロンプトキャッシングは現在Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4.5、Claude Sonnet 4、Claude Sonnet 3.7、Claude Haiku 4.5、Claude Haiku 3.5、Claude Haiku 3、Claude Opus 3(非推奨)でのみ利用可能です。
キャッシュされたシステムプロンプトとツールは、思考パラメータが変更されるときに再利用されます。ただし、思考の変更(有効/無効またはバジェット変更)は、メッセージコンテンツを含む以前にキャッシュされたプロンプトプレフィックスを無効にします。キャッシュ無効化の詳細については、キャッシュを無効にするものを参照してください。拡張思考の詳細(ツール使用とプロンプトキャッシングとの相互作用を含む)については、拡張思考ドキュメントを参照してください。
プロンプトキャッシングを有効にするには、APIリクエストに少なくとも1つのcache_controlブレークポイントを含めます。
はい、プロンプトキャッシングはツール使用やビジョン機能などの他のAPI機能と一緒に使用できます。ただし、プロンプトに画像があるかどうかを変更したり、ツール使用設定を変更したりするとキャッシュが破壊されます。キャッシュ無効化の詳細については、キャッシュを無効にするものを参照してください。
プロンプトキャッシングは新しい価格設定構造を導入しており、キャッシュ書き込みは基本入力トークンより25%多くかかり、キャッシュヒットは基本入力トークン価格の10%のみかかります。
現在、キャッシュを手動でクリアする方法はありません。キャッシュされたプレフィックスは、最小5分の非アクティブ後に自動的に期限切れになります。
APIレスポンスのcache_creation_input_tokensおよびcache_read_input_tokensフィールドを使用してキャッシュパフォーマンスを監視できます。
キャッシュ無効化の詳細については、キャッシュを無効にするものを参照してください。新しいキャッシュエントリを作成する必要がある変更のリストを含みます。
プロンプトキャッシングは強力なプライバシーとデータ分離対策で設計されています:
  1. キャッシュキーは、キャッシュコントロールポイントまでのプロンプトの暗号ハッシュを使用して生成されます。これは、同一のプロンプトを持つリクエストのみが特定のキャッシュにアクセスできることを意味します。
  2. キャッシュは組織固有です。同じ組織内のユーザーは、同一のプロンプトを使用する場合、同じキャッシュにアクセスできますが、キャッシュは異なる組織間で共有されません。同一のプロンプトであっても。
  3. キャッシング機構は、各ユニークな会話またはコンテキストの整合性とプライバシーを維持するように設計されています。
  4. プロンプト内のどこでもcache_controlを使用するのは安全です。コスト効率のため、変動性の高い部分(例:ユーザーの任意の入力)をキャッシングから除外する方が良いです。
これらの対策により、プロンプトキャッシングはパフォーマンスの利点を提供しながらデータプライバシーとセキュリティを維持します。
はい、Batches APIリクエストでプロンプトキャッシングを使用することは可能です。ただし、非同期バッチリクエストは同時に処理でき、任意の順序で処理できるため、キャッシュヒットはベストエフォートベースで提供されます。1時間キャッシュはキャッシュヒットを改善するのに役立ちます。最も費用効果的な使用方法は以下の通りです:
  • 共有プレフィックスを持つメッセージリクエストのセットを収集します。
  • この共有プレフィックスと1時間キャッシュブロックを持つ単一のリクエストのみでバッチリクエストを送信します。これはキャッシュに書き込まれます。
  • これが完了したら、残りのリクエストを送信します。完了時期を知るためにジョブを監視する必要があります。
これは通常、5分キャッシュを使用するより優れています。バッチリクエストが5分から1時間の間に完了することが一般的だからです。キャッシュヒット率を改善し、このプロセスをより簡単にする方法を検討しています。
このエラーは通常、SDKをアップグレードしたか、古いコード例を使用している場合に表示されます。プロンプトキャッシングは一般利用可能になったため、ベータプレフィックスは不要になりました。代わりに:
python client.beta.prompt_caching.messages.create(...) 
単に以下を使用してください:
python client.messages.create(...) 
このエラーは通常、SDKをアップグレードしたか、古いコード例を使用している場合に表示されます。プロンプトキャッシングは一般利用可能になったため、ベータプレフィックスは不要になりました。代わりに:
TypeScript
client.beta.promptCaching.messages.create(...) 
単に以下を使用してください:
client.messages.create(...)