プロンプトキャッシング

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

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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万トークンあたりの価格を示しています。

Model	Base tokens		Prompt caching
Name	Input	Output	5m writes	1h writes	Hits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	$4 / MTok	$20 / MTok	$5 / MTok	$8 / MTok	$0.20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.10 / MTok2
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing	$0.10 / MTokfor prompts up to 100,000 tokens	$0.50 / MTok	$0.125 / MTok	$0.20 / MTok	$0.01 / MTok
	$0.50 / MTokfor prompts over 100,000 tokens	$2.50 / MTok	$0.625 / MTok	$1 / MTok	$0.05 / MTok
Additional models
Claude Mythos 5.1	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Fable 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Mythos 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Opus 5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.8	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.7	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.6	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.1	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Opus 4	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Sonnet 5	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Sonnet 4.6	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4.5	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Haiku 4.5	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / MTok
Claude Haiku 3.5	$0.80 / MTok	$4 / MTok	$1 / MTok	$1.60 / MTok	$0.08 / MTok

^{1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.}

^{2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.}

^{All other models use the standard 0.1x multiplier.}

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

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

自動キャッシング

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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分間の「time to live」（有効期間）、すなわちTTLを使用します。基本入力トークン価格の2倍で、1時間のTTLを指定することもできます。

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

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

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

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

{
  "model": "claude-opus-5-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の位置を確認し、ブレークポイント自体を1つ目として数えます。そのウィンドウ内で一致するエントリが見つからない場合、確認は停止します（次の明示的なブレークポイントがあれば、そこから再開します）。Claude APIでは、連続するtool_useブロックの並びは1つの位置として数えられ、連続するtool_resultブロックの並びも同様です。そのため、多数の並列ツール呼び出しを含むターンだけで、前のリクエストのエントリがウィンドウの外に押し出されることはありません。

例：増え続ける会話におけるルックバック

各ターンで新しいブロックを追加し、各リクエストの最後のブロックに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%、Claude Fable 5.1およびClaude Mythos 5.1では2.5%、Claude Opus 5.5およびClaude Sonnet 5.5では5%）
• 通常の入力トークン： キャッシュされていないコンテンツ

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

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

キャッシュの制限

Claude API、Claude Platform on AWS、Google Cloud、およびMicrosoft Foundryでは、キャッシュ可能なプロンプトの最小長は次のとおりです。

• Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5、Claude Fable 5、Claude Mythos 5、およびClaude Haiku 5.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（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という階層に従います。各レベルでの変更は、そのレベルとそれ以降のすべてのレベルを無効化します。

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

会話途中のツール変更をサポートするモデルでは、inline-tools-2026-09-15ベータヘッダーを使用すると、toolsを編集せずに、会話の途中でツールを追加したり、ツールの定義を変更したりできます。会話途中のシステムメッセージ内のtool_additionブロックで定義を送信し、toolsは最初に送信したとおりのままにしておきます。キャッシュされたプレフィックスは引き続き一致するため、追加されたメッセージのみが新しい入力として処理されます。唯一の例外は、遅延されていないツールを含まないtools配列の場合で、この方法で定義された最初のツールは、そのリクエストで1回の完全なキャッシュミスを発生させます。メッセージ内でツールを定義するを参照してください。

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

レスポンス内のusage（ストリーミングの場合はmessage_startイベント）に含まれる次のAPIレスポンスフィールドを使用して、キャッシュパフォーマンスを監視します。

• cache_creation_input_tokens：新しいエントリを作成する際にキャッシュに書き込まれたトークン数。
• cache_read_input_tokens：このリクエストでキャッシュから取得されたトークン数。
• input_tokens：キャッシュから読み取られず、キャッシュの作成にも使用されなかった入力トークン数（つまり、最後のキャッシュブレークポイント以降のトークン）。

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

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

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

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

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

• ユーザーメッセージとしてツール結果のみが提供される場合、キャッシュは有効なままです
• Opus 4.5以降、Sonnet 4.6以降、およびHaiku 5.5では、ツール結果以外のユーザーコンテンツが追加された場合でも思考ブロックはデフォルトで保持されるため、キャッシュは有効なままです
• それ以前のOpus/SonnetモデルおよびClaude Haiku 4.5までの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]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)

それ以前のOpus/SonnetモデルおよびClaude Haiku 4.5までのHaikuモデルでは、この時点で以前のすべての思考ブロックがコンテキストから削除されます。Opus 4.5以降、Sonnet 4.6以降、およびHaiku 5.5では、以前の思考ブロックはデフォルトで保持され、キャッシュされたプレフィックスの一部として残ります。

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

キャッシュの保存と共有

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

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

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

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

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

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

さまざまなユースケースに向けた最適化

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

• 会話型エージェント：長い会話、特に長い指示やアップロードされたドキュメントを含む会話のコストと「latency」（レイテンシ）を削減します。
• コーディングアシスタント：関連するセクションやコードベースの要約版をプロンプトに保持することで、オートコンプリートやコードベースに関する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オブジェクト内の値の合計と等しいことに注意してください。

Web検索などのサーバーツールを使用している際に、リクエストしていないephemeral_5m_input_tokensの書き込みが表示される場合は、プロンプトキャッシングを使用したツール使用を参照してください。

1時間のキャッシュを使用する場面

定期的な頻度で使用されるプロンプト（つまり、5分ごとよりも頻繁に使用されるシステムプロンプト）がある場合は、引き続き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つのリクエストの入力トークンを表しており、それぞれ異なるキャッシュヒットとキャッシュミスがあります。その結果、それぞれ異なる料金が計算され、色付きのボックスに示されています。

キャッシュの事前ウォームアップ

「cache pre-warming」（キャッシュの事前ウォームアップ）を使用すると、ユーザーが実際のリクエストを発生させる前に、システムプロンプトやツール定義をプロンプトキャッシュに読み込んでおくことができます。これにより、最初のユーザーインタラクションでのキャッシュミスによるレイテンシのペナルティがなくなり、レイテンシが重要なアプリケーションにおいて「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-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-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-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-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 で拒否されます。これらはいずれも、トークン数0の予算では生成できない出力を前提としているためです。

• 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 のアプローチが推奨されます。出力が生成されないため、破棄すべき1トークンの応答がなく、出力トークンも課金されず、リクエストの意図も明確です。

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

プロンプトキャッシングを始めるにあたって、プロンプトキャッシングのクックブックに詳細な例とベストプラクティスが掲載されています。

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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?",
        }
    ],
)
print(response.usage.model_dump_json())

{
  "model": "claude-opus-5-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" } },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": { "timezone": { "type": "string" } },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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'd 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"},
                },
            ],
        },
    ],
)
print(response.usage.model_dump_json())

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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"},
                }
            ],
        },
    ],
)
print(response.usage.model_dump_json())

データ保持

プロンプトキャッシング（自動と明示的の両方）は、「Zero Data Retention」（ゼロデータ保持）、すなわちZDRの対象です。Anthropicは、プロンプトやClaudeの応答の生のテキストを保存しません。

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

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

よくある質問

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

client.beta.prompt_caching.messages.create(**params)

client.messages.create(**params)

client.beta.promptCaching.messages.create(/* ... */);

client.messages.create(/* ... */);