12-hour prompt caching

プロンプトキャッシュは、複数のリクエストが同じプロンプトのプレフィックス (先頭部分) を共有するときに、処理済みの結果を再利用する仕組みです。12 時間のキャッシュでは、共有の指示・ツール・コンテキストを長くキャッシュに保ちます。そのため、リクエストの間隔が数時間空いても、低いキャッシュ入力料金を適用できます。

プロンプトキャッシュは、対応する OpenAI のモデルでは既定で有効です。仕組みと前提は次のとおりです。

• キャッシュに保存されるのは key-value (KV) テンソルで、トークンそのものではありません。
• キャッシュを再利用するには、レンダリングされたプレフィックス全体が一致している必要があります。
• プロンプトキャッシュは、モデルが出力トークンを生成する方法を変えません。モデルはキャッシュ済みのプレフィックスを使って新しい応答を生成するため、同一のリクエストでも同一の出力になるとは限りません。
• キャッシュを手動で消去する機能はありません。キャッシュのエントリは、モデルのキャッシュ寿命と保持設定に従って失効します。

GPT-5.6 以降

• implicit (暗黙) と explicit (明示) の両方のキャッシュに対応します。explicit では、どのコンテキストをキャッシュに書き込むかを細かく制御できます。
• prompt_cache_options.mode が implicit のときは、OpenAI が対象となる最新のメッセージの末尾にブレークポイントを置きます。
• explicit に設定すると、開発者が選んだブレークポイントだけが使われます。ブレークポイントは、入力メッセージ内の対応するコンテンツブロックに prompt_cache_breakpoint: { "mode": "explicit" } を加えて指定します。ブレークポイントを置かない場合、そのリクエストはプロンプトキャッシュを使わず、キャッシュへの書き込みも作りません。
• 明示的ブレークポイントを複数置くと、変更の頻度が異なるプレフィックスを別々に保持できます。
• トップレベルの instructions には明示的ブレークポイントを置けません。再利用する開発者向けの指示は、developer メッセージ内の input_text ブロックに入れて指定します。
• 既知のコンテキストを前もって準備しておき、後続のリクエストで最初のトークンが返るまでの時間を縮める事前ウォームアップを使えます。まず prompt_cache_options.prewarm を true にしたリクエストを送ると、出力を生成せずにキャッシュだけを準備します。完了後、同じプレフィックスで、prewarm を省略するか false にした本来のリクエストを送ります。
• キャッシュのルーティングは OpenAI が自動で行います。prompt_cache_key を分けて使うと、アプリケーション内の顧客やユーザーごとにキャッシュの計上を分けられます。

GPT-5.6 より前のモデル

• implicit キャッシュだけに対応します。
• 保持期間は prompt_cache_retention で設定します。指定できる値はモデルによって異なります。
• 再利用可能なプレフィックスを共有する関連リクエストに、安定した prompt_cache_key を付けると、同じキャッシュへのルーティングを助けます。ただし、キャッシュヒットは保証されません。
• GPT-5.5 のキャッシュは extended prompt caching でのみ機能し、In-memory prompt caching には対応しません。

GPT-6 以降の対応モデル

• 会話の途中で推論努力度 (reasoning effort) を変えるときは、configuration_update 入力項目を追加し、トップレベルの reasoning.effort は元の値のままにします。こうすると、それまでのキャッシュ済みプレフィックスを保てます。

12 時間キャッシュへの書き込みには、入力トークン価格の 2.5 倍の料金がかかります。一方で、キャッシュされた入力には低いキャッシュ入力料金が適用されます。

キャッシュの効果は、次の方法で確認できます。

• Prompt Caching Dashboard では、キャッシュヒット率の推移、書き込みあたりの読み取り数、キャッシュ読み取り・キャッシュ書き込み・非キャッシュのトークンの内訳を確認できます。指標はモデルとサービスティアで絞り込めます。
• Prompt Cache Diagnostics tool を使うと、キャッシュミスの原因を診断できます。
• prompt_cache_options に対応する Responses API のモデルでは、レスポンスの input_tokens_details.cache_write_tokens_details に書き込み量が ttl_30m_tokens と ttl_12h_tokens に分けて示されます。

12時間プロンプトキャッシュは API で選択できます。対象となるプランや提供地域は、公式のリリースノートには記載がありません。

• ZDR が有効でない組織では、prompt_cache_retention の既定値が in_memory から 24h に変わり、extended prompt caching が既定で有効です。
• プロンプトキャッシュのすべての機能は Zero Data Retention (ZDR) と両立します。
• キャッシュは組織をまたいで共有されません。また、地域ごとの処理の境界 (regional processing boundaries) を越えて再利用されることもありません。
• キャッシュを手動で消去する機能はなく、エントリは寿命と保持設定に従って失効します。

Responses API で、キャッシュの最低寿命を 12 時間にする場合の流れです。

1. Responses API のリクエストで、prompt_cache_options.ttl を "12h" に設定します。この値は最低限のキャッシュ寿命を表し、既定値は "30m" です。
2. 明示的ブレークポイントを使っている場合は、個々のブレークポイントに prompt_cache_breakpoint.ttl を設定できます。設定すると、そのブレークポイントだけリクエスト単位の ttl が上書きされます。
3. レスポンスの input_tokens_details.cache_write_tokens_details を確認します。キャッシュへの書き込みは ttl_30m_tokens と ttl_12h_tokens に分けて示されます。