プロンプトキャッシング

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

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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分です。キャッシュされたコンテンツが使用されるたびに、追加コストなしでキャッシュが更新されます。



料金

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



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

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



自動キャッシング

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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分のTTLを使用します。基本入力トークン価格の2倍で1時間のTTLを指定できます。

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



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

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

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

{
  "model": "claude-opus-4-8",
  "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ブロックのルックバックウィンドウはすべて、明示的なブレークポイントと同様に適用されます。



エッジケース

• 最後のブロックにすでに同じ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の位置を確認し、ブレークポイント自体を最初の位置としてカウントします。そのウィンドウ内で一致するエントリが見つからない場合、チェックは停止します（または、次の明示的なブレークポイントがあればそこから再開します）。

例：増加する会話でのルックバック

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

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

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



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



キャッシュの制限

Claude API、Claude Platform on AWS、Vertex AI、およびMicrosoft Foundry（ベータ版）では、キャッシュ可能なプロンプトの最小長は以下のとおりです。

• 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 4.6、Claude Sonnet 4.5、Claude Opus 4.1（非推奨）、Claude Opus 4（Vertex AIを除き廃止）、およびClaude Sonnet 4（BedrockおよびVertex AIを除き廃止）では1,024トークン
• Claude Haiku 4.5では4,096トークン
• Claude Haiku 3.5（Vertex AIを除き廃止）では2,048トークン

モデルの利用可能性はプラットフォームによって異なり、新しくリリースされたモデルの最小値も異なる場合があります。Amazon Bedrockでは、Claude Fable 5およびClaude Mythos 5のキャッシュ可能なプロンプトの最小長は1,024トークンです。

これより短いプロンプトは、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の階層に従います。各レベルでの変更は、そのレベルとそれ以降のすべてのレベルを無効化します。

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



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

レスポンス内の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



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

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

他のコンテンツと一緒に自動キャッシング：思考ブロックは明示的に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以降では、以前の思考ブロックはデフォルトで保持され、キャッシュされたプレフィックスの一部として残ります。

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



キャッシュの保存と共有

• 組織およびワークスペースの分離： キャッシュは組織間で分離されます。異なる組織は、同一のプロンプトを使用してもキャッシュを共有することはありません。2026年2月5日以降、Claude API、Claude Platform on AWS、およびMicrosoft Foundry（ベータ版）では、組織内のワークスペースごとにもキャッシュが分離されます。BedrockおよびVertex AIは引き続き組織レベルの分離のみを使用します。

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

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



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

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

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



さまざまなユースケースへの最適化

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

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



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

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

• キャッシュされたセクションが呼び出し間で同一であることを確認します。明示的なブレークポイントの場合、cache_controlマーカーが同じ位置にあることを確認します
• 呼び出しがキャッシュの有効期間内（デフォルトで5分）に行われていることを確認します
• tool_choiceと画像の使用が呼び出し間で一貫していることを確認します
• モデルとプラットフォームの最小トークン数以上をキャッシュしていることを検証します（キャッシュの制限を参照）
• ブレークポイントがリクエスト間で同一のままであるブロックにあることを確認します。キャッシュ書き込みはブレークポイントでのみ発生し、そのブロックが変更される場合（タイムスタンプ、リクエストごとのコンテキスト、受信メッセージ）、プレフィックスハッシュは一致しません。ルックバックはブレークポイントの背後にある安定したコンテンツを見つけるのではなく、以前のリクエストが自身のブレークポイントで書き込んだエントリのみを見つけます
• 一部の言語（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オブジェクト内の値の合計に等しいことに注意してください。

ウェブ検索などのサーバーツールを使用中に、リクエストしていないephemeral_5m_input_tokensの書き込みが表示される場合は、プロンプトキャッシングとツール使用に関するこのガイドを参照してください。



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

定期的に使用されるプロンプト（つまり、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つのリクエストの入力トークンを示しており、それぞれ異なるキャッシュヒットとキャッシュミスがあります。その結果、色付きのボックスに示されているように、それぞれ異なる計算価格になります。



キャッシュのプリウォーミング

キャッシュのプリウォーミングにより、ユーザーが実際のリクエストをトリガーする前に、システムプロンプトまたはツール定義をプロンプトキャッシュにロードできます。これにより、最初のユーザーインタラクションでのキャッシュミスによるレイテンシペナルティが排除され、レイテンシに敏感なアプリケーションの「time-to-first-token」（最初のトークンまでの時間）、すなわちTTFTが短縮されます。



仕組み

リクエストでmax_tokens: 0を設定します。APIはプロンプトをモデルに読み込み、任意のcache_controlブレークポイントでキャッシュを書き込み、出力を生成せずにすぐに返します。レスポンスには空のcontent配列、stop_reason: "max_tokens"、および完全に入力されたusageブロックが含まれます。

cache_controlブレークポイントは、プレースホルダーのユーザーメッセージではなく、フォローアップリクエストと共有される最後のブロック（通常はシステムプロンプトまたはツール定義）に配置します。そうしないと、キャッシュエントリがプレースホルダーにキー付けされ、フォローアップリクエストがヒットしません。これは、自動キャッシングではなく明示的なキャッシュブレークポイントを使用することを意味します。自動キャッシングはブレークポイントを最後のブロックに配置しますが、ここではそれがプレースホルダーだからです。プレースホルダーのユーザーメッセージは、空白以外のコンテンツを含む任意の文字列にできます（ここでの例では"warmup"を使用しています）。そのコンテンツはモデルに読み込まれますが、応答されることはありません。

client = anthropic.Anthropic()

# ユーザーが到着する前にこれを実行し、共有システムプロンプトのキャッシュをウォームアップします。
prewarm = client.messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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-4-8",
        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-4-8",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# ユーザートラフィックが到着する前にキャッシュをウォームアップします。
prewarm_cache()

# その後、ユーザーがメッセージを送信する時点で、システムプロンプトのプレフィックスはすでにキャッシュされています。
response = respond("How do I implement a binary search tree?")
print(response.content[0].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

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



max_tokens=1 による回避策の置き換え

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



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

プロンプトキャッシングを始めるにあたって、プロンプトキャッシングのクックブックでは詳細な例とベストプラクティスを提供しています。

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



データ保持

プロンプトキャッシング（自動および明示的の両方）はZDR対象です。Anthropicは、プロンプトの生テキストやClaudeの応答を保存しません。

KV（キーバリュー）キャッシュ表現とキャッシュされたコンテンツの暗号化ハッシュはメモリ内にのみ保持され、永続的に保存されることはありません。キャッシュされたエントリの最小有効期間は5分（標準）または1時間（拡張）であり、その後は速やかに（ただし即座にではなく）削除されます。キャッシュエントリは組織間で分離されており、Claude API、Claude Platform on AWS、およびMicrosoft Foundry（ベータ版）では、組織内のワークスペース間でも分離されています。

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



FAQ