プロンプトキャッシュ

30K トークンのシステムプロンプトで Claude Sonnet 5 を使用する場合、キャッシュ読み取りの料金は $1.4 / 1M ではなく $0.14 / 1M です。 1セッション中に同じコンテキストを50回再送するエージェントの場合、キャッシュにより入力料金を約90%節約できます。

有効にする方法

任意のsystemブロック、メッセージ、またはツール定義にcache_control: { type: "ephemeral" }ブレークポイントを追加します。最初の呼び出しではモデルがそのブレークポイントまでの範囲をキャッシュし、以降の呼び出しで同じプレフィックスのバイト列が共有されていれば、キャッシュがヒットします。

from openai import OpenAI

client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

# Mark the large, stable prefix once with cache_control.
# Every subsequent call that sends the same prefix reads it back
# from cache at 0.10× the input rate on Claude Sonnet 5.
# Per-model rates are in the pricing table below.
SYSTEM = [
    {
        "type": "text",
        "text": open("long_system_prompt.txt").read(),
        "cache_control": {"type": "ephemeral"},
    },
]

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": "Summarize the doc above in 3 bullets."},
    ],
)

u = resp.usage
# OpenAI-compat fields populated by Kunavo:
# - prompt_tokens_details.cached_tokens — read from cache
# - cache_creation_input_tokens          — written to cache this call
print(u.prompt_tokens_details.cached_tokens,
      getattr(u, "cache_creation_input_tokens", 0))

ネイティブのMessages APIと同じワイヤ形式です。cache_controlは翻訳されず、そのままClaudeに渡されます。

# Native Anthropic Messages API — cache_control passes through untranslated.
curl https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "system": [
      {
        "type": "text",
        "text": "<your large stable system prompt>",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [
      { "role": "user", "content": "Summarize the doc above in 3 bullets." }
    ],
    "max_tokens": 1024
  }'

OpenAI形式のエンドポイントにおけるブレークポイントの自動挿入

OpenAI Chat Completions形式とResponses形式にはcache_controlフィールドがありません。OpenAIは自社サーバー上で暗黙的にキャッシュしますが、Claudeはそうではありません。Claudeがキャッシュするのは、ブレークポイントで指定された範囲のみです。そのため、OpenAI形式で通信するクライアントにはキャッシュを要求する方法がなく、リクエストをそのまま翻訳してClaudeに送るとブレークポイントは一つも含まれません。その結果、長いチャットでは毎ターン、履歴全体に対して通常の入力料金が請求されます。

Claudeモデルを/v1/chat/completionsまたは/v1/responses経由で呼び出すと、Kunavoがプロトコルで指定できないブレークポイントを設定します。有効化のための操作は不要です。対象はClaudeモデルのみです。その他のモデルファミリーは、ベンダーがブレークポイントなしで暗黙的にキャッシュするプロトコルで提供されます。

# Plain OpenAI Chat Completions — no cache_control anywhere in the body.
# The format has no field for one; Kunavo inserts the breakpoints instead.
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": LONG_SYSTEM_PROMPT},
        {"role": "user", "content": "first question"},
        {"role": "assistant", "content": "...previous answer..."},
        {"role": "user", "content": "follow-up"},
    ],
)

u = resp.usage
# Turn that writes the cache:
#   u.cache_creation_input_tokens            -> 18,000
#   u.prompt_tokens_details.cached_tokens    ->      0
# Next turn, same prefix, inside the 5-minute window:
#   u.cache_creation_input_tokens            ->    240   (only the new turn)
#   u.prompt_tokens_details.cached_tokens    -> 18,000
#
# Both stuck at 0 on a conversation well over the threshold? The prefix is
# changing between calls — a timestamp or request id inside the cached span.

ブレークポイントの配置場所と、予算を消費する順序は次のとおりです。

• 最後のメッセージに置くローリングブレークポイント — 最後のメッセージの最後のコンテンツブロックに置き、その前のすべてをキャッシュします。リクエストが会話内に残るシステムメッセージで終わる場合（後述）は、代わりにそのメッセージの直前のブロックに置きます。messagesにアシスタントのターンがすでに含まれる場合にのみ追加します。キャッシュ書き込みには1.25×の入力料金がかかるため、再送されないプロンプトに指定すると、料金が四分の一増えるだけで節約にはなりません。アシスタントによる過去のターンは、このまったく同じプレフィックスが間もなく再送されることの根拠になります。
• systemに1つ、toolsに1つ — プロンプトの安定した先頭部分に配置します。1回限りの呼び出しでも指定する価値があります。systemプロンプトを一度送る呼び出し元は、次の呼び出しでもほぼ必ず同じものを送るためです。
• 会話内に残るシステムメッセージの直前 — ローリングブレークポイントとsystem・toolsのブレークポイントで使い切らなかった予算を、後ろに何かが続くこの種のメッセージのうち最後のものの直前のブロックに置き、次にその一つ前のメッセージの直前に置きます。この種のメッセージをターンごとに動かすクライアントにしか必要ないため、最後に埋めます。この種のメッセージがない会話（ほぼすべての会話がそうです）には、この位置はありません。

2つの制約があります。プロンプト（メッセージ、system、ツールスキーマを含む）が8,192文字未満の場合、ブレークポイントは一切挿入されません。Anthropicは、独自の最小キャッシュ可能長（1,024トークン、Haikuでは2,048トークン）に満たないプレフィックスのブレークポイントを通知なく無視し、書き込み料金も読み取り料金も請求しません。その位置に指定しても効果はありません。また、Anthropicが受け付けるブレークポイントはリクエストごとに最大4個です。5個目を指定すると、何もせず無視されるのではなく、400エラーになります。

モデルが最初に回答した後に送られたシステムメッセージまたはdeveloperメッセージは、systemに引き上げられず、送られたターンのまま会話内に残ります。引き上げると、それが追加されたターンでプロンプトの先頭が変わり、履歴全体がもう一度キャッシュに書き込まれるためです。上流が受け付ける場合、Claudeはそれをシステムメッセージとして受け取り、それ以外の場合は、そのユーザーターン内の<system-reminder>タグで囲まれたテキストとして受け取ります。モデルの最初の回答より前に送られたシステムメッセージや、自身のブレークポイントで一時間のキャッシュを指定しているメッセージは、引き続きsystemに入ります。

レポートの内容は変わりません。ブレークポイントをお客様が指定した場合もゲートウェイが挿入した場合も、レスポンスフィールドで説明している同じcached_tokensフィールドとcache_creation_input_tokensフィールドに値が設定されます。そのため、使用量オブジェクトを確認すれば、挿入されたブレークポイントで実際にキャッシュがヒットしたかどうかがわかります。

料金

キャッシュ料金は各モデルの入力価格を基準に、ベンダー独自の比率で算出されます。以下の表が正式な料金であり、すべての料金は手入力ではなく、そのモデルの入力価格から計算されます。AnthropicとOpenAIのどちらでも、キャッシュの読み取り料金は入力料金の0.10×です、2件の例外：0.025× on Claude Fable 5.1, 0.05× on Claude Opus 5.5。すべてのClaudeモデルで、キャッシュの書き込み料金は入力料金の1.25×です （GPT-6 Astra、GPT-6 Sol、GPT-6 Luna、GPT-5.6 Sol、GPT-5.6 Terra にも同じ料金が適用されます）。Kunavoでは、ClaudeのTTL 1時間の書き込みも同じ1.25×で請求します。これはAnthropicの2×を下回ります。その他のモデルには書き込み専用の料金はありません。書き込みには通常の入力料金が適用されます。いずれの場合も、一度でも再利用されるプレフィックスは、新たに送信するよりキャッシュしたほうが安くなります。各料金区分にはモデル固有の割引が適用されるため、キャッシュ料金も入力料金や出力料金と同じ割合でベンダーの定価から割り引かれます。

アフィニティルーティングでキャッシュを維持

上流プロンプトキャッシュはAPIキーごとに管理されます。リクエストが毎回ランダムな上流キーに送られると、キャッシュヒット率は約1/Nになります。Kunavoはsystemプロンプトと最初のuserメッセージから安定したハッシュを生成し、同じプレフィックスを持つすべての呼び出しを同じ上流キーにルーティングします。重み付きランデブーハッシュを使用するため、プールが変更されても再マッピングされるキーは約1/Nに限られます。

設定は不要です。アフィニティルーティングはすべてのチャット呼び出しに自動で適用されます。（画像／動画／TTSはランダムにルーティングされます。これらのモダリティにはキーごとのキャッシュがありません。）

ダッシュボードの指標

呼び出しでキャッシュがヒットするようになると、選択した期間について/app/usageに2つの集計指標が表示されます。

• ヒット率 — キャッシュされた入力トークン数 ÷ 入力トークン総数。リクエストごとのトークン数から正確に算出されます。
• 節約額 — この期間に節約された米ドル額。各モデルの実際のキャッシュ読み取り料金を使ってモデルごとに計算されます（単純な平均値による近似は行いません）。これはカタログ料金での推定値です。実際の請求額はカタログ価格を下回らず、キャッシュされた呼び出しは最低料金を下回る場合があるため、この数値は実際の節約額の厳密な上限です。一般的なチャットのワークロードでは、両者の差は数パーセント以内です。

各呼び出しの詳細ページ（/app/usage/<id>）には、キャッシュ済みトークン数とキャッシュ書き込みトークン数がゼロでない場合に表示されるほか、実際の請求額も表示されます。

レスポンスフィールド

Kunavoは両方のレスポンス形式でキャッシュトークンを表示します。OpenAI互換の/v1/chat/completionsエンドポイントでは、次のとおりです。

/v1/messagesのネイティブMessages APIでは、Anthropic本来のフィールドがそのまま渡されます。

次に確認する項目

• Messages APIリファレンス — 実用的なキャッシュ例を含む、Anthropicネイティブの形式。
• Claudeプロンプトキャッシュ — キャッシュの状況を特定するための使用量オブジェクトの数値と、ゲートウェイ経由のルーティングでヒット率が低下する3つの仕組み。
• 課金と台帳 — キャッシュを考慮したmax()の最低料金と上流コストの関係。
• 完全な料金表 — すべてのチャットモデルの新規入力／出力料金と、最下部にあるキャッシュ料金の表。