Skip to Content
APIリファレンスResponses

Responses

POST /v1/responses はOpenAI Responses互換のエンドポイントです。 受け付けるフィールドと応答の形は、このページに記載した範囲です。

リクエスト

Shell
curl "$AI_GATEWAY_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<GET /v1/modelsが返したモデルID>",
    "instructions": "簡潔に答えてください。",
    "input": "ロリポップ！AIゲートウェイとは？",
    "max_output_tokens": 512
  }'

受け付けるフィールド

model と input は必須です。 ほかに instructions、max_output_tokens、temperature、top_p、tools、tool_choice、parallel_tool_calls、reasoning、text、truncation、stream、service_tier、user、prompt_cache_key、prompt_cache_retention を受け付けます。 一覧にないフィールドは読み飛ばされます。

モデルへ渡るフィールド

変換の対象は次のフィールドです。

リクエストのフィールドモデルへの渡り方
modelそのまま
input会話のメッセージへ変換
instructionssystem メッセージとして先頭に置く
max_output_tokensmax_tokens として渡す。未指定なら4096を補う
temperature、top_p、service_tierそのまま
toolstype が function のものだけ関数ツールへ変換。parameters が無ければ空のオブジェクトスキーマ
tool_choicerequired と none だけを渡す。auto は既定と同じなので送らない
prompt_cache_key、prompt_cache_retentionそのまま

受け付けはするものの現在モデルへ渡していないフィールドは、reasoning、text、truncation、parallel_tool_calls、user です。 推論結果に影響しません。

入力の扱い

input には文字列か、入力アイテムの配列を指定します。 配列で扱えるアイテムは次のとおりです。

  • message：role が assistant ならアシスタント、system と developer はシステム、それ以外はユーザーになります。 content は文字列か、input_text、output_text、text のテキストパートです。 画像などのパートは無視されます。
  • function_call：call_id、name、arguments をツール呼び出しへ変換します。
  • function_call_output：call_id と output をツールの結果へ変換します。
  • compaction、compaction_trigger：コンテキストの圧縮に使います。

input が文字列でも配列でもない場合は 400 が返ります。

レスポンス

JSON
{
  "id": "...",
  "object": "response",
  "created_at": 1750000000,
  "status": "completed",
  "model": "<実際に応答したモデル>",
  "output": [
    {
      "id": "...",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "...", "annotations": [] }]
    }
  ],
  "parallel_tool_calls": true,
  "error": null,
  "incomplete_details": null,
  "usage": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 }
}

ツール呼び出しがある場合は、output に type が function_call のアイテムが続きます。 テキストもツール呼び出しもない場合は、空文字列の message アイテムがひとつ返ります。 status は成功時つねに completed、parallel_tool_calls は固定値です。 model にはリクエストの指定ではなく、実際に応答したモデルの公開名が入ります。

コンテキストの圧縮

input に compaction_trigger アイテムを含めると、それまでの会話を要約する指示を追加して実行し、type が compaction の出力ひとつだけを返します。 要約は encrypted_content に入ります。 次のリクエストで type が compaction のアイテムとしてこの値をそのまま送り返すと、要約が会話の先頭に復元されます。 Codex CLIはこの仕組みでコンテキストを圧縮します。

キャッシュ

Claudeの明示キャッシュに対応する場合は、input のメッセージ内コンテンツパートへ cache_control を指定できます。 TTLを選べるClaudeでは、TTLなし（default）、5m、1hを指定できます。 対応していないモデルやTTLを指定すると 400 が返ります。 prompt_cache_key は対応するGPTモデルで使えます。 条件はプロンプトキャッシュで説明します。

ストリーミング

stream: true を指定すると、response. で始まるイベント名のServer-Sent Eventsで返ります。

Chat CompletionsMessages