プロンプトキャッシング

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

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

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

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

client = anthropic.Anthropic()

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

有効期間は、キャッシュエントリを書き込むまたは読み取るリクエストの開始時点から計測され、そのレスポンスの終了時点からではありません。レスポンスの生成に費やされた時間は有効期間に対してカウントされます。たとえば、レスポンスのストリーミングに 4 分かかる場合、同じキャッシュされたプレフィックスを再利用する後続のリクエストは、そのレスポンスが完了してから約 1 分以内に開始する必要があります。



料金

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



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

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



自動キャッシング

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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-5",
  "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、Google Cloud、および Microsoft Foundry では、キャッシュ可能なプロンプトの最小長は次のとおりです。

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

これらの最小値は、各モデルが利用可能なすべてのプラットフォームに適用されます。

これより短いプロンプトは、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：キャッシュから読み取られず、キャッシュの作成にも使用されなかった入力トークン数（つまり、最後のキャッシュブレークポイント以降のトークン）。



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

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

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

より詳細な情報については、思考とプロンプトキャッシングを参照してください。



キャッシュの保存と共有

• 組織とワークスペースの分離： キャッシュは組織間で分離されます。異なる組織は、同一のプロンプトを使用してもキャッシュを共有することはありません。Claude API、Claude Platform on AWS、および Microsoft Foundry では、キャッシュは組織内のワークスペースごとにも分離されます。Bedrock と Google Cloud は組織レベルの分離のみを使用します。

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

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



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

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

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



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

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

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



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

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

• キャッシュされたセクションが呼び出し間で同一であることを確認してください。明示的なブレークポイントの場合、cache_control マーカーが同じ位置にあることを確認してください
• 呼び出しがキャッシュの有効期間内（デフォルトで 5 分）に行われていることを確認してください
• tool_choice、画像の使用、思考設定、および output_config.effort が呼び出し間で一貫していることを確認してください
• モデルとプラットフォームの最小トークン数以上をキャッシュしていることを確認してください（キャッシュの制限を参照）
• ブレークポイントがリクエスト間で同一のままであるブロックにあることを確認してください。キャッシュ書き込みはブレークポイントでのみ発生し、そのブロックが変わる場合（タイムスタンプ、リクエストごとのコンテキスト、受信メッセージ）、プレフィックスハッシュは一致しません。ルックバックはブレークポイントの背後にある安定したコンテンツを見つけるのではなく、以前のリクエストが自身のブレークポイントで書き込んだエントリのみを見つけます
• 一部の言語（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 ブレークポイントは、プレースホルダーのユーザーメッセージではなく、後続のリクエストと共有される最後のブロック（通常はシステムプロンプトまたはツール定義）に配置してください。そうしないと、キャッシュエントリがプレースホルダーにキー付けされ、後続のリクエストがキャッシュにヒットしません。また、後続のリクエストと同じ思考設定および output_config.effort を使用してください。これらの値はプロンプトにレンダリングされるため（キャッシュを無効化する要因を参照）、異なる設定でプリウォームすると、実際のトラフィックがヒットしないエントリが書き込まれる可能性があります。これは、自動キャッシングではなく明示的なキャッシュブレークポイントを使用することを意味します。自動キャッシングは最後のブロックにブレークポイントを配置しますが、ここではそれがプレースホルダーになるためです。プレースホルダーのユーザーメッセージは、空白以外の内容を含む任意の文字列にできます（ここでの例では "warmup" を使用しています）。その内容はモデルに読み込まれますが、応答されることはありません。

client = anthropic.Anthropic()

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


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

# その後、ユーザーがメッセージを送信する時点で、システムプロンプトのプレフィックスはすでにキャッシュされています。
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.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 リクエスト内でも拒否されます。プリウォームは「time-to-first-token」（最初のトークンまでの時間）を対象としていますが、これはバッチ処理には適用されず、バッチ処理中に書き込まれたキャッシュエントリは後続のリクエストが実行される前に期限切れになる可能性が高いためです。



max_tokens=1 の回避策の置き換え

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



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

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

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



データ保持

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

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

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



FAQ