OpenRouterのPrompt CachingとSticky Routingとは？料金を読む条件

Prompt Cachingは、system prompt、tool定義、長い参照資料など、複数turnで同じ部分を再利用するための仕組みです。Sticky Routingはcacheを持つproviderへ後続turnを戻しやすくしますが、対応条件が揃ったかはusageのcached_tokensなどで確認します。

Prompt Cachingは、毎回同じ入力なら必ず安くなる機能ではない

cache readが通常入力より安いproviderもありますが、最初のcache write、短すぎるprompt、TTL切れ、固定prefixの変更、provider移動でhitしないことがあります。Anthropicのように5分・1時間のTTLやcache writeの価格が分かれる例もあるため、providerの説明を一括して扱いません。

Sticky Routingは、cacheのための条件付きの戻り道

OpenRouterの公式Docsでは、cacheを使ったrequestのproviderを記憶し、同じmodelの後続requestを同じprovider endpointへ戻す仕組みとして説明されています。デフォルトは会話の冒頭メッセージをもとに会話を識別し、session_idを指定すればその値をrouting keyに使います。手動のprovider.orderを指定した場合は明示した順序が優先されます。

• multi-turn agentの会話ごとにsession_idを安定させる
• session_idは最大256文字。ユーザーの秘密情報や生のpromptをそのままIDにしない
• sticky providerが不調ならfallbackが起こり、別providerでcache missや価格差が生じ得る
• session_idを使えばcache hit前からsticky routingが始まると公式Docsにあるが、成功requestと利用条件は確認する

server-sideでcache hitを確認する最小例

以下はOpenRouter公式Docsにあるsession_id・cache_control・Chat Completionsの契約を、server-sideのPythonで確認する最小例です。API keyは環境変数から読み、レスポンスのusageだけを観測します。model名とTTLは例であり、料金や提供状態の固定値ではありません。

import os
import requests

payload = {
    "model": "~anthropic/claude-sonnet-latest",
    "session_id": "agent-session-2026-07-29",
    "cache_control": {"type": "ephemeral"},
    "messages": [
        {"role": "system", "content": "Use the project policy and return a short plan."},
        {"role": "user", "content": "Review this task."},
    ],
}

response = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
data = response.json()
usage = data.get("usage", {})
prompt_details = usage.get("prompt_tokens_details", {})
print({
    "cached_tokens": prompt_details.get("cached_tokens"),
    "cache_write_tokens": prompt_details.get("cache_write_tokens"),
    "cache_discount": usage.get("cache_discount"),
})

cache hitを料金の証拠にする確認順

• 同じmodel、同じprovider条件、同じ固定prefixで2回以上の小さなテストをする
• cached_tokensが増えたか、cache_write_tokensが初回だけかをusageで見る
• cache_discount、入力・出力token、失敗・retry、最終providerを同じログで残す
• session_idやprovider指定を変えたテストを別条件として比較する
• 料金は公式model pageと請求画面で再確認し、単一テストから節約率を推定しない