Messages APIを使用してプロンプトキャッシュを実装する方法の例を以下に示します。

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "あなたは文学作品を分析するAIアシスタントです。あなたの目標は、テーマ、登場人物、文体について洞察に満ちたコメントを提供することです。"
      },
      {
        "type": "text",
        "text": "ジェーン・オースティンの高慢と偏見... [ここに完全なテキストコンテンツを配置]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "高慢と偏見の主要なテーマを分析してください。"
      }
    ]
  }'

応答：

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

この例では、「高慢と偏見」の全文がcache_controlパラメータを介してキャッシュされています。これにより、この長いテキストを複数回のAPI呼び出しで再利用でき、毎回再処理する必要がなくなります。ユーザーメッセージを変更するだけで、キャッシュされたコンテンツを利用しながら、この本に関するさまざまな質問をすることができ、応答速度が向上し、効率が向上します。

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

プロンプトキャッシュが有効なリクエストを送信すると、次のようになります。

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

これは、次のようなシナリオで特に役立ちます。

  • 大量の例を含むプロンプト
  • 大量のコンテキストまたは背景情報
  • 一貫した指示を持つ繰り返しのタスク
  • 長時間の複数ターン会話

キャッシュのデフォルトの有効期間は5分で、キャッシュされたコンテンツが使用されるたびに更新されます。また、より長いキャッシュ期間が必要なシナリオ向けに、**1時間キャッシュバージョン（ベータ版）**もサポートしています。

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

プロンプトキャッシュは、tools、system、messagesを順序通りに含み、cache_controlでマークされたコンテンツブロックまで、プロンプト全体を参照します。

​
キャッシュの料金

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

モデル基本入力トークン5分キャッシュ書き込み1時間キャッシュ書き込みキャッシュヒットと更新出力トークン
Claude Opus 4プラットフォーム価格1.25倍基本価格2倍基本価格0.1倍基本価格プラットフォーム価格
Claude Sonnet 4プラットフォーム価格1.25倍基本価格2倍基本価格0.1倍基本価格プラットフォーム価格
Claude Sonnet 3.7プラットフォーム価格1.25倍基本価格2倍基本価格0.1倍基本価格プラットフォーム価格
Claude Sonnet 3.5プラットフォーム価格1.25倍基本価格2倍基本価格0.1倍基本価格プラットフォーム価格
Claude Haiku 3.5プラットフォーム価格1.25倍基本価格2倍基本価格0.1倍基本価格プラットフォーム価格
Claude Opus 3プラットフォーム価格1.25倍基本価格2倍基本価格0.1倍基本価格プラットフォーム価格
Claude Haiku 3プラットフォーム価格1.25倍基本価格2倍基本価格0.1倍基本価格プラットフォーム価格

注意：

  • 5分キャッシュ書き込みトークン価格は基本入力トークン価格の1.25倍です。
  • 1時間キャッシュ書き込みトークン価格は基本入力トークン価格の2倍です。
  • キャッシュ読み取りトークン価格は基本入力トークン価格の0.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の順に作成されます。

cache_controlパラメータを使用すると、最大4つのキャッシュブレークポイントを定義でき、異なる再利用可能な部分を個別にキャッシュできます。各ブレークポイントについて、システムは以前の位置のキャッシュヒットを自動的にチェックし、見つかった場合は最長の合致するプレフィックスを使用します。

​
キャッシュの制限

最小キャッシュ可能プロンプト長は以下の通りです。

  • 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がマークされていても、短いプロンプトはキャッシュできません。この量より少ないトークンをキャッシュしようとするリクエストは、キャッシュを使用せずに処理されます。プロンプトがキャッシュされたかどうかを確認するには、応答の使用状況フィールドを確認してください。

同時リクエストの場合、キャッシュエントリは最初の応答が開始された後にのみ利用可能になることに注意してください。並列リクエストのキャッシュヒットが必要な場合は、後続のリクエストを送信する前に最初の応答を待ってください。

現在、2種類のキャッシュタイプがサポートされています。

  • “ephemeral”：デフォルトの5分間の有効期間
  • 1時間キャッシュ（ベータ版）：より長いキャッシュ期間が必要なシナリオ向け

​
1時間キャッシュ期間（ベータ版）

より長いキャッシュ期間が必要なシナリオ向けに、1時間キャッシュオプションを提供しています。

拡張キャッシュを使用するには、リクエストにextended-cache-ttl-2025-04-11をベータヘッダーとして追加し、cache_control定義にttlを含める必要があります。

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "長期的な指示...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​
1時間キャッシュを使用するタイミング

1時間キャッシュは特に以下の場合に役立ちます。

  • バッチ処理ジョブ：共通のプレフィックスを持つ大量のリクエストを処理する場合
  • 長時間のセッション：長い指示やアップロードされたドキュメントを含む、長期間にわたってコンテキストを維持する必要がある会話
  • 大規模なドキュメント分析：同じドキュメントに対して複数回異なる種類の分析を行う場合
  • コードベースの質問応答：長期間にわたって同じコードベースに対して複数回クエリを実行する場合

​
異なるTTLの組み合わせ

同じリクエスト内で異なるキャッシュ期間を組み合わせることができます。

{
  "system": [
    {
      "type": "text", 
      "text": "長期的な指示...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "短期的なコンテキスト...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​
キャッシュ可能なコンテンツ

リクエスト内の各ブロックはcache_controlでキャッシュを指定できます。これには以下が含まれます。

  • ツール：tools配列内のツール定義
  • システムメッセージ：system配列内のコンテンツブロック
  • メッセージ：messages.content配列内のコンテンツブロック。ユーザーとアシスタントの会話ターンを含む
  • 画像とドキュメント：ユーザー会話ターン中のmessages.content配列内のコンテンツブロック
  • ツール使用とツール結果：ユーザーとアシスタント会話ターン中のmessages.content配列内のコンテンツブロック

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

​
キャッシュできないコンテンツ

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

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

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

応答内のこれらのAPI応答フィールド（またはストリーミング時のmessage_startイベント）を介してキャッシュパフォーマンスを監視します。

  • cache_creation_input_tokens: 新しいキャッシュエントリが作成されたときにキャッシュに書き込まれたトークン数
  • cache_read_input_tokens: キャッシュから取得されたトークン数
  • input_tokens: キャッシュから読み取られなかった、またはキャッシュの作成に使用された入力トークン数

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

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

  • システム指示、背景情報、大規模なコンテキスト、または頻繁に使用されるツール定義など、安定した再利用可能なコンテンツをキャッシュします。
  • 最高のパフォーマンスを得るために、キャッシュコンテンツをプロンプトの先頭に配置します。
  • 異なるキャッシュ可能なプレフィックス部分を区切るために、キャッシュブレークポイントを戦略的に使用します。
  • キャッシュヒット率を定期的に分析し、必要に応じて戦略を調整します。
  • 長期的に使用するコンテンツの場合、より良い費用対効果のために1時間キャッシュの使用を検討します。

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

シナリオに応じてプロンプトキャッシュ戦略を調整します。

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

​
よくある問題の解決

  • キャッシュ部分が異なる呼び出し間で完全に同じであり、同じ位置にcache_controlがマークされていることを確認してください。
  • 呼び出しがキャッシュの有効期間内（5分または1時間）であることを確認してください。
  • tool_choiceと画像の有無が呼び出し間で一貫していることを確認してください。
  • キャッシュしたトークン数が最小要件を満たしていることを確認してください。
  • システムはキャッシュブレークポイントより前の位置のキャッシュされたコンテンツを使用しようとしますが、追加のcache_controlパラメータを使用して、プロンプトの前の部分のキャッシュを確実に検索できます。これは、非常に長いコンテンツブロックのリストを含むクエリに役立つ場合があります。

tool_choiceまたはプロンプト内の任意の場所の画像の有無を変更すると、キャッシュが無効になり、新しいキャッシュエントリが作成されることに注意してください。

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

  • 組織の分離： キャッシュは組織間で分離されています。異なる組織は、同じプロンプトを使用してもキャッシュを共有することはありません。
  • 正確な一致： キャッシュヒットには、cache_controlでマークされたブロックの前のすべてのテキストと画像、およびそれ自体を含む、100%同じプロンプトセグメントが必要です。キャッシュの読み取りと作成中に、同じブロックをcache_controlでマークする必要があります。
  • 出力トークンの生成： プロンプトキャッシュは出力トークンの生成には影響しません。受け取る応答は、プロンプトキャッシュを使用しない場合とまったく同じです。

​
異なるモデルのサポート状況

  • プロンプトキャッシュのサポートは、モデル自体に依存します。
  • モデル自体がサポートしており、関連するパラメータを明示的に宣言する必要がない場合、OpenAI互換形式での転送はサポートされます。
  • OpenAIはデフォルトでプロンプトキャッシュをサポートしており、キャッシュは課金されず、キャッシュされたトークンの読み取り費用は半額になります。5〜10分間再利用されない状態が続くと自動的にクリアされます。ドキュメント
  • Claudeはネイティブのcache_control: { type: "ephemeral" }宣言が必要です。キャッシュ料金は通常の入力の1.25倍（5分）または2倍（1時間）で、キャッシュされたトークンの読み取り費用は0.1倍です。有効期間は5分または1時間です。ドキュメント
  • Deepseek V3とR1はネイティブでサポートされており、キャッシュ料金は通常の入力の1倍で、キャッシュされたトークンの読み取り費用は0.1倍です。ドキュメント
  • Geminiモデルは暗黙的なキャッシュをサポートしています。
    • 暗黙的なキャッシュ：すべてのGemini 2.5モデルでデフォルトで有効になっています。リクエストがキャッシュにヒットした場合、コスト削減が自動的に適用されます。この機能は2025年5月8日から有効です。コンテキストキャッシュの最小入力トークン数：Gemini 2.5 Flashは1,024、Gemini 2.5 Proは2,048。
      • 暗黙的なキャッシュヒット率を高めるヒント：
        • 共通の大きなコンテンツブロックをプロンプトの先頭に配置します。
        • 短期間にプレフィックスが類似するリクエストを送信してみてください。
      • 応答オブジェクトのusage_metadataフィールドで、キャッシュヒットしたトークン数を確認できます。
      • コスト削減は、プリフィルキャッシュヒット数に基づいて測定されます。プリフィルキャッシュとYouTubeビデオのプリプロセスキャッシュのみが暗黙的なキャッシュをサポートしています。