prompt_cache_options.ttl を設定し、キャッシュの最小保持時間を 30 分または 12 時間から選択できます。例では gpt-6.1-terra を使用します。
12 時間のキャッシュは
/v1/responses のみ対応し、/v1/chat/completions では使用できません。TTL は最小保持時間であり、削除期限や毎回のキャッシュヒットを保証するものではありません。API キーを設定する
例の長文はプレースホルダーです。再利用する実際の内容に置き換えてください。キャッシュ対象のプレフィックスには 1,024 トークン以上が必要です。この短いプレースホルダーだけではキャッシュは書き込まれません。
30 分のキャッシュを使用する
prompt_cache_options.ttl を "30m" に設定します。ttl を省略しても 30 分になります。mode の省略時は暗黙的キャッシュが使用され、上流サービスがキャッシュのブレークポイントを自動で選択します。
12 時間のキャッシュを使用する
同じフィールドを"12h" に変更します。他のリクエスト構造は同じです。
固定プレフィックスで異なる質問に対応する
同じ長文を再利用して最後の質問だけを変更する場合は、mode を "explicit" にし、固定内容の末尾の input_text ブロックに prompt_cache_breakpoint を追加します。この例は 12 時間です。30 分にするにはリクエストの ttl を "30m" に変更してください。
mode: "explicit" のみを設定し、ブレークポイントを追加しない場合、キャッシュの読み書きは行われません。以下のブレークポイントには個別の TTL がないため、リクエストの prompt_cache_options.ttl を継承します。キャッシュの利用状況を確認する
レスポンスのusage.input_tokens_details を確認します。
cached_tokens: 今回キャッシュから読み取ったトークン数。0 より大きければキャッシュが読み取られています。cache_write_tokens: 今回キャッシュに書き込んだトークンの合計数。cache_write_tokens_details.ttl_30m_tokens: 今回 30 分の TTL で書き込んだトークン数。cache_write_tokens_details.ttl_12h_tokens: 今回 12 時間の TTL で書き込んだトークン数。
cached_tokens を確認してください。プレフィックスが短すぎる場合、内容が変わった場合、キャッシュにヒットしない場合は 0 になることがあります。
キャッシュ usage の例と集計方法
以下は、キャッシュに対応する OpenAI モデルで両方の TTL の書き込みがある場合のレスポンス抜粋です。usage のみを示しています。値は実際のレスポンスで確認してください。
input_tokens に含まれています。TTL 別の 2 つの値は cache_write_tokens の内訳です。合計と内訳を重複して加算したり、キャッシュの読み書きを入力合計に加算したりしないでください。
この例では、通常の入力は 12000 - 4000 - 7000 = 1000、書き込みは 5000 + 2000 = 7000、合計トークン数は 12000 + 1000 = 13000 です。
キャッシュの動作は OpenAI 公式キャッシュガイドを参照してください。