プロンプトキャッシュ

プロンプトキャッシュは、モデルごとの対応状況に沿ったフィールドだけを受け付けます。 対応していないフィールドを指定したリクエストは、モデルへ送る前に 400 で止まります。 対応状況は組織のモデル情報から判定するため、同じリクエストでも指定したモデルによって結果が変わります。

cache_control

明示的なキャッシュに対応するモデルでは、キャッシュしたい範囲の末尾に cache_control を付けます。 Chat Completionsでは、メッセージ、メッセージ内のコンテンツパート、tools とその function に付けられます。 Responsesでは、入力メッセージのコンテンツパートと tools に付けられます。 Messagesでは、system、メッセージのコンテンツブロック、tools に付けられます。

{
  "model": "<GET /v1/modelsが返したモデルID>",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "長い共通の前提...",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    { "role": "user", "content": "質問" }
  ]
}

• 明示的なキャッシュに対応していないモデルを指定すると 400 が返ります。
• フォールバック候補を含め、実行される可能性があるすべてのモデルが対応している必要があります。
• ttl を指定する場合は、そのモデルが選べる値だけを指定できます。
• Claudeでは 5m と 1h を選べます。
• Nova系のモデルは暗黙的なキャッシュを利用するため、cache_control を指定しないでください。
• ボディのトップレベルに置いた cache_control は無効です。
• メッセージやブロックの中に置いてください。
• Responses APIでは、Claudeの明示キャッシュに限り、入力メッセージのコンテンツパートに cache_control を付けられます。

prompt_cache_key

暗黙的なキャッシュに対応する一部のGPTモデルでは、prompt_cache_key に文字列を指定して、同じ前提を共有するリクエストをまとめられます。 文字列以外を指定すると 400 が返ります。 対応していないモデルを指定した場合も 400 です。

使えないフィールド

次のフィールドは、キャッシュ情報を持つモデルでは受け付けません。 指定すると 400 が返ります。

エラーメッセージ

キャッシュのエラーは、指定したモデル名と、代わりに使える方法を含んだメッセージで返ります。 allowed alternative: のあとに、そのフィールドの代わりに使える指定が入ります。

{
  "error": {
    "message": "<model>: cache_control is not supported; ...",
    "type": "bad_request",
    "code": "bad_request"
  }
}