Claude キャッシュ課金

GPT/Gemini の自動キャッシュとは異なり、Claude のネイティブ API におけるプロンプトキャッシュは明示的に宣言します: cache_control を使ってキャッシュ対象のブロックを指定します。ヒットすると、その部分はキャッシュ倍率で課金されます。

使い方

system またはメッセージのコンテンツブロックに cache_control を追加します:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<数千字のルール文書またはナレッジベース>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "ルールに基づいて回答:……" }]
}

ヒットの確認

応答の usage では:

{
  "usage": {
    "input_tokens": 42,
    "cache_creation_input_tokens": 4810,
    "cache_read_input_tokens": 0,
    "output_tokens": 213
  }
}

• 初回呼び出し: cache_creation_input_tokens がキャッシュ作成として計上される(標準料金よりやや高い);
• 以降のヒット: cache_read_input_tokens がキャッシュ倍率で課金される(標準料金より大幅に安い);
• キャッシュ有効期限は数分単位で、継続して呼び出すと自動的に延長されます。

実践的な推奨

• キャッシュポイントは長くて安定した内容の後ろに置く: system プロンプト、ツール定義、参考文書;
• キャッシュ対象の内容は1文字単位まで一致している必要があり、テンプレートにタイムスタンプなど変動しやすいフィールドを混ぜないこと;
• 低頻度の呼び出し(間隔がキャッシュの存続期間を超える場合)ではヒットせず、キャッシュ作成を繰り返すとむしろ高くなる—— 低頻度のシナリオでは cache_control を付けない;
• OpenAI 互換 API 経由で Claude を呼び出す場合、キャッシュは上位レイヤーで自動処理されるため、このパラメータは不要。 詳しくはキャッシュ課金を参照してください。