cache_control で指定した部分だけをキャッシュします。
プロンプトキャッシュを使っても、推論はリクエストごとに実行されます。同じリクエストに以前の回答を返すものではありません。
プロンプトをキャッシュする
変わらない部分の最後のブロックに印を付けます。そのブロックまでのすべて(そのブロックを含む)がキャッシュされます。- リクエストを一度送り、キャッシュを書き込みます。
- 同じキャッシュ対象の内容で、もう一度送ります。
- レスポンスの使用量にある
cached_tokensとcache_write_tokens(使用量と料金のフィールドを参照)と、リクエスト詳細のキャッシュメーターを確認します。 - 最初の 1 回だけでなく、複数回の呼び出しでレイテンシとコストを比較します。
Phaseo は各プロバイダーに、そのプロバイダーが文書化しているキャッシュ制御だけを送り、それ以外は取り除きます。キャッシュ制御によってプロバイダーがルーティングから除外されることはありません。各モデルページにキャッシュの読み取りと書き込みの料金が掲載されています。
自動でキャッシュするプロバイダー
その他の OpenAI 互換プロバイダーには、API が受け付ける場合に
prompt_cache_key が送られ、それ以外のキャッシュ制御は送られません。Phaseo はキーそのものではなく、常にワークスペースとキーのハッシュを送ります。プロバイダーアフィニティを参照してください。
キャッシュ制御
Claude のブレークポイントを Phaseo に配置させる
Chat Completions、Responses、Anthropic Messages でトップレベルにcache_control を指定すると、Claude のルートでキャッシュが有効になり、Phaseo がブレークポイントを配置します。他のプロバイダーはこれを無視します。
ttl: "5m"(既定)を、モデルが長期間のキャッシュエントリに対応している場合は ttl: "1h" を使います。トップレベルの cache_control は会話を 1 つのプロバイダーに留める効果もあります。プロバイダーアフィニティを参照してください。
provider_options.anthropic.cache_control は同じ設定で、scope も指定できます。リクエストが両方を送った場合は、provider_options の値が優先されます。
複数ステップのツールループには
agent を使います。all_text と last_user_message はツール結果だけを含むメッセージに印を付けないため、キャッシュされるプレフィックスが伸びなくなります。認識できない scope の値は agent として扱われます。
ブロックに自分で設定したブレークポイントは既定のポリシーより優先され、Anthropic のリクエストあたり 4 個という上限に数えられます。既定のポリシーは 4 個に達すると印の追加をやめます。自分のブロックに 4 個を超える印がある場合、Phaseo は最初の 1 個と最新の 3 個を残して他を取り除くため、リクエストは拒否されません。
ブロックにキャッシュのブレークポイントを置く
コンテンツブロックにキャッシュの印を付けると、そのブロックまでのすべて(そのブロックを含む)がキャッシュされます。Phaseo は 2 つの書き方を受け付けます。cache_control:{"type": "ephemeral"}。任意で5mまたは1hのttlを指定します。prompt_cache_breakpoint: OpenAI の{"mode": "explicit"}。任意で30mまたは12hのttlを指定します(OpenAI の 12 時間キャッシュを参照)。1 つのブロックに両方がある場合は、prompt_cache_breakpointが優先されます。
cache_control を受け付けます。system のテキストブロック、メッセージのテキストと画像のブロック、ツール結果のブロック、ツール定義です。1 つのリクエストに複数の TTL がある場合、Anthropic では 1h のブレークポイントを 5m のものより前に置く必要があります。
各プロバイダーには、それぞれの形式で印が送られます。
ツール定義の印が届くのは、Claude のルート、Alibaba Model Studio、Venice、Inference.net の Claude と Gemini 2.5 のモデルだけです。OpenAI はツールのブレークポイントを受け付けません。印を削除してもプロンプトの残りは変わらないため、キャッシュされるプレフィックスは印のないリクエストと一致します。
Amazon Bedrock と Google Vertex AI は Claude 3.7 Sonnet、3.5 Sonnet、3 Opus を 5 分間だけキャッシュし、Bedrock はこれらのモデルで
ttl を拒否することがあります。これらのルートでは、Phaseo はブレークポイントを ttl なしで送るため 5 分間キャッシュされ、削除した 1h を X-Phaseo-Dropped-Params ヘッダーと meta.routing.dropped_params で cache_control.ttl として報告します。Inference.net は ttl なしのブレークポイントを文書化しているため、Phaseo はそこでも同じように ttl を削除して報告し、書き込みは 5 分の書き込みとして課金されます。
OpenAI の保持期間とオプション
OpenAI のキャッシュ制御はモデルの世代によって異なります。Phaseo は、受け付けられる場所にだけそれぞれを送ります。explicit モードでは、自分で配置したブレークポイントだけがキャッシュされます。DeepInfra では、セッション内のすべてのリクエストに prompt_cache_key も必要です。Phaseo は Moonshot AI の 1h を、1 時間の書き込み料金がある Kimi K3 のルートにだけ送るため、その書き込みはその料金で課金されます。それ以外では ttl を削除し、X-Phaseo-Dropped-Params ヘッダーで prompt_cache_options.ttl として報告します。他のプロバイダーにはどちらのフィールドも送られません。
どちらのフィールドも、トップレベルか provider_options.openai の下で送れます。両方ある場合は、トップレベルの値が優先されます。
24h を使います。
OpenAI の 12 時間キャッシュ
GPT-5.6 以降では、ttl: "12h" を設定すると、OpenAI はキャッシュエントリを少なくとも 12 時間保持します。リクエスト全体なら prompt_cache_options に、1 つのブレークポイントなら prompt_cache_breakpoint に指定します。独自の ttl を持たないブレークポイントはリクエストの値を使います。OpenAI は 12 時間の書き込みを入力料金の 2.5 倍、30 分の書き込みを 1.25 倍で課金します。キャッシュ読み取りの料金はどちらも同じです。
- OpenAI が 12 時間の保持期間を文書化しているのは Responses API だけです。これを求める Chat Completions のリクエストは OpenAI の Responses API で実行され、レスポンスは Chat Completions の形式のまま返されます。
- 12 時間キャッシュを受け付けるルートが先に試されます。対象は OpenAI 自身の API(
openaiとopenai-eu)で、料金カードに 12 時間の書き込み料金がある GPT-5.6 以降のモデルです。Azure OpenAI、他のプロバイダー、GPT-5.6 より前のモデルなど、それ以外のルートにはこの設定なしでリクエストが送られるため、30 分の既定値が適用されます。リクエストは引き続き実行され、削除されたフィールドはX-Phaseo-Dropped-Paramsヘッダーとmeta.routing.dropped_paramsでprompt_cache_options.ttlまたはprompt_cache_breakpoint.ttlとして報告されます。
Gemini の明示的なキャッシュを使う
Gemini 2.5 以降は、何も送らなくても暗黙的にキャッシュします。Google のキャッシュ API で作成した明示的なキャッシュを使うには、その名前をprovider_options.google.cached_content に渡します。
- Google AI Studio では、
cached_contentは自分の Google API キー(BYOK)でのみ機能します。Phaseo のキーを使うと、キャッシュは作成したアカウントに属するため、リクエストは400を返します。 - Vertex AI では、
cached_contentは自分の Vertex AI 認証情報でのみ機能し、Phaseo の認証情報では400を返します。キャッシュの完全な名前projects/{project}/locations/{location}/cachedContents/{id}を送ると、Phaseo はそのプロジェクトとロケーションにリクエストを送ります。cachedContents/abc123のような短い名前では、サービスアカウント JSON のproject_idとregionが使われ、どちらかがない場合は400を返します。 - Google は Gemini 4 Argon 以降で明示的なキャッシュに対応していません。
provider_options.google.cache_control と provider_options.google.cache_ttl は受け付けられますが、Google には送られません。
Responses:会話全体を送る
Phaseo はレスポンスを保存しません。previous_response_id または conversation を設定したリクエストは 400 unsupported_param を返すため、各ステップで会話全体を input に入れて送ってください。その変わらない冒頭部分がキャッシュされるプレフィックスになります。ツールループでは reasoning の出力項目も送り返してください。ツールループでの推論を参照してください。
会話の途中で推論の度合いを変える
Chat Completions のreasoning_effort または Responses の reasoning.effort をリクエスト間で変更すると、Phaseo は Claude のプロンプトキャッシュを保ちます。変更は新しいトップレベルの度合いではなく、messages 内の度合いマーカーとして送られます。これは Claude の推論を変更せずに送り返している限り機能します。Anthropic Messages では、マーカーを自分で送ります。会話の途中で推論の度合いを変えるを参照してください。
使用量と料金のフィールド
すべてのテキストエンドポイントは、キャッシュの読み取りと書き込みを報告します。Chat Completions と Responses は OpenAI のセマンティクスに従い、入力数にキャッシュの読み取りと書き込みが含まれます。Anthropic Messages は Anthropic のセマンティクスに従い、input_tokens にはそれらが含まれません。
Chat Completions と Responses では、キャッシュされていない入力は、入力の合計からキャッシュ読み取りとキャッシュ書き込みを引いた値です。ストリーミングされる Anthropic Messages のレスポンスでは、キャッシュのフィールドは
message_delta に含まれます。OpenAI がそこに内訳を文書化していないため、Chat Completions の使用量には保持期間別の内訳がありませんが、リクエスト詳細には記録されます。
以前のレスポンスでは、キャッシュ書き込みは
output_tokens_details.cached_tokens(Chat Completions では completion_tokens_details.cached_tokens)として報告され、Claude のルートは Chat Completions と Responses で input_tokens からキャッシュの読み取りと書き込みを除いていました。どちらももう当てはまりません。書き込みは cache_write_tokens から読み取ってください。ストリーミングしない Anthropic Messages のレスポンスは以前 cache_creation_input_tokens: null を返していましたが、現在は実際の数を返します。キャッシュされたトークンの料金
Phaseo は各入力トークンを一度だけ、1 つの料金で課金します。キャッシュされていない入力は入力料金、キャッシュ読み取りはキャッシュ読み取り料金、キャッシュ書き込みはキャッシュ書き込み料金です。プロバイダーが別々に料金を設定している場合は、5 分と 1 時間の料金(Claude)、または 30 分と 12 時間の料金(OpenAI)になります。キャッシュ書き込みを入力の合計に含めるプロバイダーもあれば、それとは別に報告するプロバイダーもありますが、どちらの場合も書き込んだトークンが通常の入力として二重に課金されることはありません。 たとえば、入力 100 万トークンあたり $5.00、キャッシュ読み取り $0.50、30 分のキャッシュ書き込み $6.25、出力 $30.00 という例示の料金で、入力 53,100 トークン(うち 48,000 がキャッシュ読み取り、3,000 がキャッシュ書き込み)と出力 850 トークンのリクエストの料金は次のとおりです。
そのうち 2,000 の書き込みが 12 時間の保持期間だった場合、その料金は $6.25 ではなく 100 万あたり $12.50 になり、リクエストのコストは $0.09125 になります。
一部のモデルでは、キャッシュされたトークンを割り引かないプロバイダーもあります。そのモデルページでは、入力とキャッシュ読み取りが同じ料金で表示されます。
ルートにまだキャッシュ料金がない場合
カタログにまだキャッシュ料金がないルートでプロバイダーがキャッシュされたトークンを報告しても、リクエストは失敗しません。- キャッシュ読み取りは、ルートの入力料金で課金されます。
- キャッシュ書き込みは、入力料金にプロバイダーが文書化した書き込みの倍率を掛けた料金で課金されます。
- 料金の行には
pricing_fallback: "input_rate"が付きます。
カタログにキャッシュ書き込み料金が 1 つだけある Claude のルートでは、その料金は 5 分の料金です。プロバイダーが 1 時間の書き込みとして報告した書き込みは、
pricing_fallback: "input_rate" が付いた cached_write_text_tokens_1h の行で、入力料金の 2 倍で課金されます。
ストリーミングされる Claude のレスポンスの最後の message_delta は、TTL の内訳なしでキャッシュ書き込みの合計を報告します。サーバーツールの書き込みはリクエストが 1 時間を求めていても 5 分を使うことがあるため、内訳を超える書き込みは 5 分の書き込みとして課金されます。
プロバイダーアフィニティ
プロンプトキャッシュは 1 つのプロバイダー、多くの場合はそのプロバイダーの 1 つのリージョンやデプロイにあります。Phaseo は関連するリクエストを、それを処理したプロバイダーとルートに留めるため、エージェントループが別の場所でキャッシュを作り直すコストを払わずに済みます。 会話を固定するには、prompt_cache_key または session_id を送るか、cache_control(トップレベル、provider_options.anthropic.cache_control、またはメッセージブロックやツールの cache_control か prompt_cache_breakpoint の印)でキャッシュをオプトインします。Phaseo は最初に成功したリクエストを処理したプロバイダーとルートに会話を固定し、同じキーを持つ後続のリクエストもそこに送ります。固定はワークスペース、エンドポイント、モデルごとに保持されます。
固定が続く期間は、プロバイダーのキャッシュ保持期間によって決まります。
固定が移るのは、そのプロバイダーが失敗したとき(サーキットブレーカーが開いている、または最近のエラー率が高い)、そのプロバイダーでの Phaseo の管理クォータを使い切ったとき、または有効なルート、プリセット、ガードレール、リクエストポリシーがそのプロバイダーを許可しなくなったときだけです。その場合リクエストはフェイルオーバーし、固定はそれを処理したプロバイダーに移ります。リクエスト詳細では、ルーティング診断に
sticky_routing.demotionReason として記録されます。固定されたリクエストが、復旧中のプロバイダーの確認に使われることはありません。
キー、session_id、キャッシュの印がなくても、Phaseo は冒頭のコンテキストを、それについてキャッシュ読み取りまたはキャッシュ書き込みを報告したプロバイダーに 15 分間固定します。ただし、そのプロバイダーのキャッシュされた入力が通常の入力より安い場合に限ります。
Phaseo はプロバイダーに、生のキーではなくワークスペースと prompt_cache_key のハッシュを送るため、2 つのワークスペースで同じキーを使ってもプロバイダーのキャッシュが共有されることはありません。session_id だけがある場合、Phaseo は OpenAI、xAI、Fireworks、Cerebras 向けにセッションからそのハッシュを導出します。Fireworks、Cloudflare Workers AI、Baseten は x-session-affinity ヘッダーでも、Morph は x-session-id ヘッダーでも受け取り、xAI は provider_options.xai.conversation_id を設定していない限り x-grok-conv-id として受け取ります。レスポンスには引き続き自分の prompt_cache_key がそのまま返されます。
1 つのリクエストでオプトアウトするには、provider.cache_aware_routing を false に設定します。リクエストに session_id があっても通常のコンテキストベースのルーティングだけを使いたい場合は、routing.session_affinity を false に設定します。この場合、Phaseo はセッションからプロバイダーのキャッシュキーを導出することもやめます。アフィニティとプロバイダーの順序やフォールバックの関係については、ルーティングとフォールバックを参照してください。すべてのキャッシュフィールドはパラメーターリファレンスにも掲載されています。