プロンプトキャッシュ

プロンプトキャッシュは、プロンプト内の特定のプレフィックスから再開することで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-1-20250805",
    "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呼び出しで再利用できます。ユーザーメッセージのみを変更することで、キャッシュされたコンテンツを活用しながら本について様々な質問をすることができ、より高速な応答と効率の向上につながります。

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

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

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

これは特に以下の場合に有用です：

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

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

5分が短すぎる場合、Anthropicは1時間のキャッシュ期間も提供しています。1時間キャッシュは現在ベータ版です。

詳細については、1時間キャッシュ期間を参照してください。

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

プロンプトキャッシュは、cache_controlで指定されたブロックまでの完全なプロンプト - tools、system、messages（この順序で）を参照します。

料金

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

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output 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	$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 (deprecated)	$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 (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
Claude Sonnet 3.7
Claude Sonnet 3.5
Claude Haiku 3.5
Claude Haiku 3
Claude Opus 3

プロンプトの構造化

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

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

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

静的コンテンツの最後に1つのキャッシュブレークポイントを使用するだけで、システムが自動的に最も長い一致するプレフィックスを見つけます。 仕組みは以下の通りです：

cache_controlブレークポイントを追加すると、システムは自動的に以前のすべてのコンテンツブロック境界（明示的なブレークポイントの約20ブロック前まで）でキャッシュヒットをチェックします
これらの以前の位置のいずれかが以前のリクエストからのキャッシュされたコンテンツと一致する場合、システムは最も長い一致するプレフィックスを使用します
これは、キャッシュを有効にするために複数のブレークポイントが必要ないことを意味します - 最後に1つあれば十分です

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

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

異なる頻度で変更される異なるセクションをキャッシュする（例：ツールはほとんど変更されないが、コンテキストは毎日更新される）
何がキャッシュされるかをより詳細に制御する
最終ブレークポイントから20ブロック以上前のコンテンツのキャッシュを確実にする

重要な制限: 自動プレフィックスチェックは、各明示的なブレークポイントから約20コンテンツブロック前までしか遡りません。プロンプトにキャッシュブレークポイントより前に20を超えるコンテンツブロックがある場合、それより前のコンテンツは追加のブレークポイントを追加しない限りキャッシュヒットがチェックされません。

キャッシュの制限

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

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分の有効期間があります。

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

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

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

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

キャッシュできるもの

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

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

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

キャッシュできないもの

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

思考ブロックはcache_controlで直接キャッシュできません。ただし、思考ブロックは以前のアシスタントターンに現れる場合、他のコンテンツと一緒にキャッシュできます。この方法でキャッシュされた場合、キャッシュから読み取られるときに入力トークンとしてカウントされます。
サブコンテンツブロック（引用など）自体は直接キャッシュできません。代わりに、トップレベルブロックをキャッシュしてください。

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

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

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

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

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

変更内容	ツールキャッシュ	システムキャッシュ	メッセージキャッシュ	影響
ツール定義	✘	✘	✘	ツール定義（名前、説明、パラメータ）の変更はキャッシュ全体を無効にします
ウェブ検索トグル	✓	✘	✘	ウェブ検索の有効/無効はシステムプロンプトを変更します
引用トグル	✓	✘	✘	引用の有効/無効はシステムプロンプトを変更します
ツール選択	✓	✓	✘	`tool_choice`パラメータの変更はメッセージブロックのみに影響します
画像	✓	✓	✘	プロンプト内のどこかでの画像の追加/削除はメッセージブロックに影響します
思考パラメータ	✓	✓	✘	拡張思考設定（有効/無効、予算）の変更はメッセージブロックに影響します
拡張思考リクエストに渡される非ツール結果	✓	✓	✘	拡張思考が有効な間に非ツール結果がリクエストで渡されると、以前にキャッシュされたすべての思考ブロックがコンテキストから削除され、それらの思考ブロックに続くコンテキスト内のメッセージはキャッシュから削除されます。詳細については、思考ブロックでのキャッシュを参照してください。

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

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

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

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

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

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

異なる使用ケースの最適化

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

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

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

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

キャッシュされたセクションが同一で、呼び出し間で同じ場所でcache_controlでマークされていることを確認します
呼び出しがキャッシュの有効期間内（デフォルトで5分）に行われていることを確認します
tool_choiceと画像使用が呼び出し間で一貫していることを確認します
最小トークン数以上をキャッシュしていることを確認します
システムは以前のコンテンツブロック境界（ブレークポイントの約20ブロック前まで）でキャッシュヒットを自動的にチェックします。20を超えるコンテンツブロックを持つプロンプトの場合、すべてのコンテンツがキャッシュされるようにするために、プロンプトの早い段階で追加の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]
# 非ツール結果のユーザーブロックにより、すべての思考ブロックが無視されます
# このリクエストは思考ブロックが存在しなかったかのように処理されます

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

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

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

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

1時間キャッシュ期間

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

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つの課金場所を決定します：

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

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

課金されるのは：

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

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

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

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

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

大きなコンテキストキャッシュの例

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-opus-4-1-20250805",
    "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-opus-4-1-20250805",
    "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_weatherおよびget_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-opus-4-1-20250805",
    "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-opus-4-1-20250805",
    "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）：最後のツール定義のcache_controlパラメータは、すべてのツール定義をキャッシュします。
再利用可能な指示キャッシュ（キャッシュブレークポイント2）：システムプロンプト内の静的指示は別々にキャッシュされます。これらの指示はリクエスト間でほとんど変更されません。
RAGコンテキストキャッシュ（キャッシュブレークポイント3）：知識ベース文書は独立してキャッシュされ、ツールや指示キャッシュを無効にすることなくRAG文書を更新できます。
会話履歴キャッシュ（キャッシュブレークポイント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つあれば十分ですか？

キャッシュブレークポイントは追加コストがかかりますか？

キャッシュの有効期間はどのくらいですか？

いくつのキャッシュブレークポイントを使用できますか？

プロンプトキャッシュはすべてのモデルで利用できますか？

プロンプトキャッシュは拡張思考とどのように連携しますか？

プロンプトキャッシュを有効にするにはどうすればよいですか？

プロンプトキャッシュを他のAPI機能と一緒に使用できますか？

プロンプトキャッシュは料金にどのような影響を与えますか？

キャッシュを手動でクリアできますか？

キャッシュ戦略の効果をどのように追跡できますか？

キャッシュを破損させるものは何ですか？

プロンプトキャッシュはプライバシーとデータ分離をどのように処理しますか？

Batches APIでプロンプトキャッシュを使用できますか？

Pythonで「AttributeError: 'Beta' object has no attribute 'prompt_caching'」エラーが表示されるのはなぜですか？

このエラーは通常、SDKをアップグレードしたか、古いコード例を使用している場合に表示されます。プロンプトキャッシュは現在一般提供されているため、ベータプレフィックスは不要になりました。以下の代わりに：

python client.beta.prompt_caching.messages.create(...)

単純に以下を使用してください：

python client.messages.create(...)

「TypeError: Cannot read properties of undefined (reading 'messages')」が表示されるのはなぜですか？

TypeScript
client.beta.promptCaching.messages.create(...)

単純に以下を使用してください：

client.messages.create(...)

用語集拡張思考

On this page

プロンプトキャッシュの仕組み
料金
プロンプトキャッシュの実装方法
サポートされているモデル
プロンプトの構造化
自動プレフィックスチェックの仕組み
複数のブレークポイントを使用する場合
キャッシュの制限
キャッシュブレークポイントコストの理解
キャッシュできるもの
キャッシュできないもの
キャッシュを無効にするもの
キャッシュパフォーマンスの追跡
効果的なキャッシュのベストプラクティス
異なる使用ケースの最適化
一般的な問題のトラブルシューティング
思考ブロックでのキャッシュ
キャッシュストレージと共有
1時間キャッシュ期間
1時間キャッシュを使用する場合
異なるTTLの混在
プロンプトキャッシュの例
FAQ

はじめの手順

モデルと料金

Claudeについて学ぶ

機能

ツール

Model Context Protocol (MCP)

使用事例

プロンプトエンジニアリング

テスト・評価

ガードレールを強化

リーガルセンター

プロンプトキャッシュ

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

料金

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

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

プロンプトの構造化

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

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

キャッシュの制限

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

キャッシュできるもの

キャッシュできないもの

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

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

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

異なる使用ケースの最適化

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

思考ブロックでのキャッシュ

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

1時間キャッシュ期間

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

異なるTTLの混在

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

FAQ

はじめの手順

モデルと料金

Claudeについて学ぶ

機能

ツール

Model Context Protocol (MCP)

使用事例

プロンプトエンジニアリング

テスト・評価

ガードレールを強化

リーガルセンター

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

​料金

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

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

​プロンプトの構造化

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

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

​キャッシュの制限

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

​キャッシュできるもの

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

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

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

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

​異なる使用ケースの最適化

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

​思考ブロックでのキャッシュ

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

​1時間キャッシュ期間

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

​異なるTTLの混在

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

​FAQ

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

料金

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

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

プロンプトの構造化

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

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

キャッシュの制限

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

キャッシュできるもの

キャッシュできないもの

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

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

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

異なる使用ケースの最適化

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

思考ブロックでのキャッシュ

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

1時間キャッシュ期間

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

異なるTTLの混在

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

FAQ