OpenRouter、プロンプトキャッシュと固定ルーティングを発表

エージェントは、会話の各ターンで同じシステムプロンプトやツール定義、スキーマ、ポリシー指示を繰り返し送信しています。6 ターンのセッションであれば、ユーザーの最新メッセージやエージェントの最新ツール結果が変更されただけなのに、最初のブロックに対して 6 回も請求が発生してしまいます。

これを解決するのが「プロンプトキャッシング」です。プロバイダーはプロンプトの重複部分をキャッシュから読み取るため、毎回フル価格で課金する必要がなくなります。また、「スティッキールーティング」によって、セッションを同じプロバイダーに維持し、キャッシュされた状態をターンを超えて継続させます。

この記事では、コストに関する実務的な側面について解説します。キャッシュされたトークンの料金体系、なぜキャッシュの読み取りと書き込みで価格が異なるのか、session_id がどのようにして最初のターンからエージェントのセッションをホットな状態に保つのか、そしてキャッシングが実際に機能しているかを確認する方法です。

Tl;dr

• キャッシュからの読み取りコストは、プロバイダーによりますが新規入力トークンの 0.1 倍〜0.5 倍程度です。Claude Sonnet 4.6 では、キャッシュ読み取りが $0.30/M（100 万トークンあたり）で、新規入力が $3.00/M なので、正確に 0.1 倍の価格になります。

• 最初のリクエストではキャッシュへの書き込みコストが発生します。Anthropic の場合、書き込み料金は入力料金の 1.25 倍（TTL 5 分）または 2.0 倍（TTL 1 時間）です。つまり、一度も再利用されない書き込みは、キャッシングを行わない場合よりも高額になります。

• 次のリクエストが同じプロバイダーのエンドポイントに到達しない限り、ホットなキャッシュの恩恵は受けられません。70 社以上のプロバイダーが存在する中で、2 ターン目には冷たいエンドポイントに接続され、フル価格を請求される可能性があります。

• 私たちのスティッキールーティングでは、フォローアップリクエストをホットなキャッシュを持つプロバイダーに固定します。また、session_id を使用することで、キャッシュヒットが発生する前の最初の成功したリクエストから強制的にその動作を開始させます。

キャッシュミスが発生する原因は主に 4 つあります。プロンプトが短すぎる、キャッシュの有効期限が切れている、先頭のブロックが頻繁に更新される、あるいはリクエストが別のプロバイダーへ転送された場合です。キャッシュヒットを確認するには、レスポンス内の cached_tokens をチェックしてください。

プロンプトキャッシングでトークンコストはどれくらい削減できるか？

キャッシュからの読み取りコストは、プロバイダーによって異なりますが、通常の入力価格の 0.1 倍から 0.5 倍です。この価格差こそが、エージェントループのコストを大幅に下げる要因となります。

繰り返し使用される部分は、往々にして最も高価な部分です。長いシステムプロンプト、ツールの定義、JSON スキーマ、ガードレール、取得したドキュメント、あるいはモデルの一貫性を保つための例などが該当します。キャッシングを行わない場合、各ターンでこれらすべてに対してフルプライスが発生します。一方、キャッシングを利用すれば、最初のリクエストでキャッシュに書き込まれ、その後のリクエストでは低価格で読み出されます。

以下にプロバイダー別の詳細を示します：

詳細な仕組みについては、プロンプトキャッシングのドキュメントをご覧ください。実際の金額はモデルやプロバイダーの経路によって異なりますが、この倍率指標を使えば、そのプロバイダーにおけるキャッシュされた入力と通常入力のコスト比較を把握できます。

エージェント開発者にとって、このパターンの本質はシンプルです。最初のターンではキャッシュ構築のために費用がかかりますが、同じ冒頭ブロックを再利用する限り、その後のすべてのターンで大幅にコストを抑えられます。

コストの内訳：キャッシュ書き込みと読み出し

プロンプトキャッシングには「書き込み」と「読み出し」の 2 つのコストが発生します。

書き込みは、プロバイダーがプロンプトの再利用可能な部分を保存する際に行われます。読み出しは、後続のリクエストでその保存されたコンテンツを再利用する際に行われます。同じコンテンツを十分に多く読み出せば、書き込みコストを上回るメリットを得られます。

一部のプロバイダーでは、書き込みコストが通常入力よりも高くなります。Anthropic の場合、デフォルトの 5 分 TTL では入力の 1.25 倍、1 時間の TTL では 2.0 倍の入力コストがかかります。一度も再利用されなかった Anthropic のキャッシュ書き込みは、キャッシングなしで同じプロンプトを送信するよりも高額になります。

単発のリクエストであれば、キャッシングが役立つとは限りません。しかし、マルチターン型エージェントでは反復利用が前提です。セッション全体を通じて、エージェントは同じ指示、ツール、スキーマ、ポリシーコンテキストを引き継ぎます。つまり、数回のターンで書き込みコストは回収できるのです。

短いバーストで次のリクエストがすぐに届く場合は、5 分のキャッシュ有効期限（TTL）を使用します。セッションが一時的に中断され、デフォルトのキャッシュが期限切れになる可能性はあるものの、そのコンテンツを保持する価値がある場合は、1 時間の TTL を使用してください。

なぜウォームキャッシュが次のリクエストで常に役立つわけではないのか？

ウォームキャッシュが有効なのは、次のリクエストがそのキャッシュを保持しているプロバイダーのエンドポイントに到達した場合に限られます。

リクエストが複数のプロバイダーにルーティングされる場合、1 回目のターンでキャッシュが作成されたプロバイダーとは異なる場所で 2 回目のターンが処理されることがあります。すると、2 番目のプロバイダーには読み取るためのウォームキャッシュが存在しません。リクエスト自体は正常に動作しますが、料金は全額請求され、cached_tokens の値は低く抑えられたまま、あるいはゼロになります。

そこで、プロンプトキャッシングとスタティックルーティング（Sticky Routing）を組み合わせるのです。キャッシュされたリクエストの後、同じモデルに対する続報のリクエストは、そのプロバイダーのキャッシュ読み取り料金が通常の入力料金より安い場合、同じプロバイダーのエンドポイントへルーティングします。もしそのスタティックなプロバイダーが利用不可になった場合は、OpenRouter はリクエストを失敗させるのではなく、次に利用可能なプロバイダーにフォールバックします。

デフォルトでは、OpenRouter は最初のシステムまたは開発者メッセージと、最初の非システムメッセージのハッシュ値を会話の識別子として認識しています。これは、これらの冒頭メッセージが一定である場合に機能します。

しかし、エージェントはこのルールを破ることがよくあります。状態の要約やツールのコンテキストの再配置、新しいランメタデータの追加などにより、最初のメッセージを書き換えるケースがあるのです。冒頭のメッセージが変わればハッシュ値も変わり、会話が異なるプロバイダーにルーティングされてしまいます。この問題を解決するには、明示的に session_id を指定する必要があります。

セッション ID で最初からキャッシュを温めておく

エージェントのループ処理では、session_id を設定してください。これを指定すると、OpenRouter は最初のメッセージからキーを導出するのではなく、この session_id をそのまま「スティッキー・ルーティング」のキーとして直接使用します。

session_id を指定すると、キャッシュヒットが発生する前でも、最初の成功したリクエストの直後にステッキールーティングが有効になります。これを指定しない場合、キャッシュヒットが検出されてからしかステッキールーティングは開始されません。複数回の対話を行うエージェントにとっては、これが「1 巡目から確実に機能するキャッシュ」と「時々しか効かないキャッシュ」の違いを意味します。

session_id はリクエスト本文の最上位フィールドとして送信するか、x-session-id ヘッダーを通じて渡すことができます。会話やエージェントの実行中は値を安定させ、文字数は 256 文字以内に抑えてください。

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "session_id": "my-agent-session-abc123",
    "messages": [{"role": "system", "content": "..."}]
  }'

from openrouter import OpenRouter

client = OpenRouter()

resp = client.chat.send(
    model="anthropic/claude-sonnet-4.6",
    session_id="my-agent-session-abc123",
    messages=[{"role": "system", "content": "..."}],
)

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const response = await openRouter.chat.send({
  model: 'anthropic/claude-sonnet-4.6',
  session_id: 'my-agent-session-abc123',
  messages: [{ role: 'system', content: '...' }],
});

作業単位に合わせた値を使用してください。チャットスレッド、チケット、ワークフロー実行、エージェントタスクなどが該当します。各ターンで新しい session_id を作成すると、キャッシュを保持しているプロバイダへのリクエストが停止してしまいます。

Auto Router や Pareto Router といったルーターモデルを利用している場合、セッションのスティッキネス（接続維持）機能はプロバイダーだけでなく、ルーターが選択したモデル自体も固定します。これにより、セッション中にモデルが切り替わるのを防ぎ、動作の一貫性を保つとともにキャッシュを温かい状態に維持できます。

プロンプトキャッシングが実際に機能しているか確認するには？

最も手っ取り早い方法は、利用状況のインスペクション を行うことです。

レスポンス内の usage.prompt_tokens_details.cached_tokens は、キャッシュから読み込まれたトークンの数を示します。この値がゼロより大きい場合、リクエストはキャッシュにヒットしたことを意味します。また、cache_write_tokens はキャッシュ書き込みリクエスト中に書き込まれたトークンの数を表示します。

{
  "usage": {
    "prompt_tokens": 10339,
    "completion_tokens": 60,
    "total_tokens": 10399,
    "prompt_tokens_details": {
      "cached_tokens": 10318,
      "cache_write_tokens": 0
    }
  }
}

この例では、プロンプトトークンのほとんどがキャッシュから取得され、今回のリクエストで新しいキャッシュエントリは作成されていません。

キャッシュの動作を確認するには、以下の 3 つの場所を参照してください。Activity ページ の詳細ビュー、/api/v1/generation API、および API レスポンスに含まれる usage.prompt_tokens_details オブジェクトです。

cache_discount を使用すると、生成時にどれほど節約できたかを確認できます。書き込みに対して課金されるプロバイダーでは、キャッシュへの書き込みが通常の入力よりも高額な場合、書き込みターンで割引率がマイナスになることがあります。ただし、その後のキャッシュ読み取りターンでは、割引率は正の値に戻ります。

キャッシュミスが発生する理由と、その対策

キャッシュが機能していないように見える場合、通常は以下の 4 つのいずれかが原因です。プロンプトが短すぎる、キャッシュの有効期限が切れた、冒頭のコンテンツが変更された、あるいはリクエストが異なるプロバイダーへ流れてしまったケースです。

プロンプトがプロバイダーの最小サイズに満たない

すべてのプロバイダーにはキャッシュ対象となる最小のプロンプトサイズが存在し、それ未満では何もキャッシュされません。Anthropic においては、Claude Opus 4.5〜4.8 および Claude Haiku 4.5 は 4,096 トークンが必要で、Claude Haiku 3.5 は 2,048 トークンが必要です。一方、Claude Sonnet 4、4.5、4.6（および Opus 4 / 4.1）は 1,024 トークンで十分です。OpenAI も 1,024 トークンを必要とします。Gemini 2.5 Pro は 4,096 トークンが必要ですが、Gemini 2.5 Flash では 1,024 トークンで済みます。

再利用可能なコンテンツがこれらの最小サイズを下回っている場合、キャッシュは開始されません。無理にダミーテキストを追加して強引にサイズを大きくする必要はありません。ツール、スキーマ、取得したドキュメント、例示データ、ポリシー文書など、すでに大量の再利用可能なコンテンツがある場所でキャッシングを活用しましょう。

会話の間にキャッシュが期限切れになる

キャッシュは永続的なものではありません。Anthropic のデフォルト有効期限は 5 分ですが、長時間のセッションには 1 時間オプションも用意されています。Gemini の暗黙的なキャッシュは約 3〜5 分で切れますが、読み取りを行ってもリセットされることはありません。一度キャッシュが期限切れになると、次のリクエストでは新しいキャッシュを再作成する必要があります。

ユーザーがターン間で頻繁に一時停止する場合は、サポートされている場合により長い TTL（有効期限）を設定するか、アイドル期間後に新しい書き込みを受け付けるようにエージェントを設計してください。

プロンプトの冒頭が頻繁に変更される

自動キャッシュと暗黙的キャッシュは、プロンプトの冒頭部分が一定である場合に最も効果的に機能します。安定した要素を先に配置し、変動する要素を後に配置しましょう。具体的には、システム指示、ツール定義、スキーマ、固定された参照資料などを先頭に置き、ユーザーからの質問、タイムスタンプ、一時的な状態、ツールの出力、短命のメタデータなどは後方に配置します。

細かい点にも注意が必要です。最初のシステムメッセージにタイムスタンプが含まれていると、ターンごとにプロンプトが新規のものとして認識されてしまいます。キャッシュ対象に含まれる必要がない場合は、そのタイムスタンプを後のユーザーメッセージやツールメッセージへ移動させましょう。

リクエストが異なるプロバイダーに流れてしまう

キャッシュは作成された場所に存在します。後続のリクエストが別のプロバイダーエンドポイントにルーティングされると、そのエンドポイントは以前のキャッシュを読み取ることができません。

エージェントワークフローでは session_id を設定し、スティッキー・ルーティングによってセッションをホットなプロバイダー上に維持するようにしてください。ただし注意点として、自分で provider.order を設定した場合、その順序指定がスティッキー・ルーティングよりも優先されます。特定の provider 順序が必要な場合は、provider ルーティング制御 を利用してください。

エージェントループにおけるキャッシュとスティッキー・ルーティングの併用

エージェントがターンごとに同じコンテンツを送信する場合、以下のチェックリストを確認してください。

• 安定したコンテンツを先頭に配置する：システムプロンプト、ツール定義、スキーマ、ポリシー、長期にわたるコンテキストなど。

変更されるコンテンツは後回しにする：ユーザーメッセージ、ツール結果、タイムスタンプ、および実行固有の状態。

明示的な cache_control が必要なプロバイダーに対してプロンプトキャッシュを有効化する。

会話またはワークフローの実行に対して安定した session_id を設定する。

キャッシュトークン (cached_tokens) とキャッシュ割引率 (cache_discount) を確認し、読み込みが正しく行われているか検証してください。

大まかなイメージとして、同じ 10,000 トークンを 6 ターンにわたって繰り返すエージェントを想定してみましょう。

この例では、繰り返し出現するコンテンツのみを対象とし、頻繁に変わる小さなメッセージやモデルの出力トークンは対象外としています。会話のターン数が増えるほど、コスト削減効果は大きくなります。

使い分けの目安:

• 再利用されるコンテンツが会話の進行とともに増加する多ターン対話には、自動キャッシュを活用してください。
• キャッシュすべき大規模なブロック（取得したドキュメント、長い参照ファイル、キャラクター設定カード、CSV データ、ポリシーテキストなど）を明確に把握している場合は、明示的なキャッシュブレイクポイントを使用します。
• エージェントセッション、サポートチケット、チャットスレッド、ワークフロー実行、あるいは会話の冒頭メッセージがターンごとに変わるようなケースでは、session_id を利用してください。
• デフォルトの 5 分キャッシュではターン間に期限切れになる可能性がある、より長い Anthropic セッションには 1 時間キャッシュを使用します。短く密度の高い往復通信の場合はデフォルト設定で十分です。

エージェントが同じ高コストなコンテンツを繰り返し送信する場合でも、キャッシュ読み込みとスティッキー・ルーティングを活用すれば、それがループ内で最も高額な部分になるのを防げます。

FAQ

OpenRouter はプロンプトキャッシュに対応していますか？

はい、OpenRouter は対応するプロバイダーとモデル全体でプロンプトキャッシングをサポートしています。ほとんどのプロバイダーでは自動的に有効化されますが、Anthropic と Alibaba Qwen の場合は cache_control を使用して明示的にキャッシュを管理します。

キャッシュされたトークンの読み取りコストは、プロバイダーによって通常の入力価格の 0.1 倍から 0.5 倍です。つまり、一度リクエストを送信すれば、その後の再利用ではプレフィックス部分の費用が大幅に下がります。

OpenRouter でキャッシュされたトークンはいくらになる？

プロバイダーによって異なりますが、キャッシュ読み取りのコストは通常の入力価格の 0.1 倍から 0.5 倍です。Anthropic、DeepSeek、Alibaba Qwen は 0.1 倍で読み取れます。OpenAI は 0.25 倍から 0.50 倍、Gemini、Grok、Moonshot は 0.25 倍、Groq は 0.5 倍です。

OpenRouter を通じてプロンプトキャッシングが機能しないのはなぜ？

プロバイダーのトークン最低額に満たないプロンプト、期限切れのキャッシュ、不安定なプロンプトプレフィックス、またはターン間のプロバイダーのドリフトなどが一般的な原因です。エージェントワークフローでは、まず安定した session_id を設定し、使用状況レスポンス内の cached_tokens を確認してください。値がゼロを超えていれば、キャッシュヒットが成功したことを意味します。

エージェントのターン間でキャッシュを温かく保つにはどうすればよいですか？

会話、チケット、またはワークフロー実行に対して安定した session_id を渡してください。OpenRouter はこれをステッキールーティングキーとして使用するため、フォローアップのリクエストは、ウォームキャッシュを保持している同じプロバイダーエンドポイントへルーティングされます。session_id が設定されると、キャッシュヒットが観測される前に、最初の成功したリクエストの後にステッキ性が有効化されます。

キャッシュによって節約された金額を確認するには？

キャッシュの読み取りは usage.prompt_tokens_details.cached_tokens を、書き込みは cache_write_tokens をそれぞれ確認してください。cached_tokens の値がゼロより大きければ、キャッシュヒットしたことを意味します。

生成ごとのコスト効果を確認するには、レスポンス内の cache_discount を参照するか、Activity ページ の詳細ビューを開いてください。

「/api/v1/generation」API について。

Auto Router でキャッシュは有効か？

はい、有効です。session_id を設定すれば、Auto Router や Pareto Router といったルーターモデルが、会話中に解決されたモデルとプロバイダーを固定します。そのため、続行されるリクエストも同じ暖かいキャッシュにヒットし続けることになります。