Responses

POST /v1/responses

指定した入力に対してモデル応答を生成します。OpenAI Responses API と互換です。

リクエストボディ

パラメータ	型	必須	説明
model	string	はい	モデル ID
input	string | array	はい	テキスト文字列 (ユーザーメッセージとして扱われる) または入力アイテムの配列
instructions	string	いいえ	コンテキストの先頭に追加されるシステム / デベロッパーメッセージ
stream	boolean	いいえ	SSE でストリーミング。デフォルト: false
temperature	number	いいえ	サンプリング温度 (0〜2)
top_p	number	いいえ	Nucleus サンプリング (0より大きく1以下)
max_output_tokens	integer	いいえ	生成トークン数の上限
tools	array	いいえ	モデルが呼び出し可能な関数ツール
tool_choice	string | object	いいえ	"none"、"auto"、"required"、または特定のツール
parallel_tool_calls	boolean	いいえ	並列ツール呼び出しを許可
reasoning	object	いいえ	{ "effort": …, "summary": "auto"|"concise"|"detailed" }。effort はモデルごとにその reasoning_efforts と照合されます。一覧にないレベルは一つ上のレベル(なければ最も高いレベル)で実行され、送信したレベルより高コストになる場合があります。適用されたレベルは X-Reasoning-Effort で返されます。effort の語彙にない値は 400 になります。
truncation	string	いいえ	"auto" (コンテキストに収まるよう切り詰め) または "disabled"
metadata	object	いいえ	トラッキング用のキーバリューペア
text	object	いいえ	テキストレスポンスフォーマットの設定
seed	integer	いいえ	決定論的サンプリングのシード
stop	string | string[]	いいえ	最大 4 つの停止シーケンス
top_k	integer	いいえ	Top-k サンプリング (プロバイダ依存)
repetition_penalty	number	いいえ	繰り返しペナルティ (プロバイダ依存)

モデルが reasoning をオフにできるのは、その levels に none が含まれる場合だけです。none を公開していないモデルへ reasoning.effort に none を送ると 400 になります。エラー文は エラー にあります。

入力タイプ

単純な文字列:

{
  "model": "google/gemma-4-31b-it",
  "input": "Explain quantum computing in one paragraph."
}

構造化された入力アイテム:

{
  "model": "google/gemma-4-31b-it",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Describe this image" },
        { "type": "input_image", "image_url": "https://..." }
      ]
    }
  ]
}

入力アイテムのタイプ:

タイプ	説明
メッセージ	{ "role": "user"|"assistant"|"developer"|"system", "content": string | content[] }
関数呼び出し	{ "type": "function_call", "call_id": "...", "name": "...", "arguments": "..." }
関数呼び出しの出力	{ "type": "function_call_output", "call_id": "...", "output": "..." }

コンテンツタイプ: input_text、input_image、input_file

input_image の image_url、input_file の file_url、MCP ツールの server_url は URL の要件 を満たす必要があります。

PDF は、input_file にドキュメントの file_id を指定するか、file_data (data:application/pdf;base64,...) としてインラインで送信します。インラインの PDF は document ファイルとして保存され、制限は Chat Completions と同じです（ゼロデータリテンションの組織では保存されずメモリ上で描画され、専用の制限が適用されます）。サーバーが各ページを画像に変換し、1 ページにつき 1 つの input_image パートとしてモデルに渡します。

レスポンス

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "created_at": 1700000000,
  "model": "google/gemma-4-31b-it",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Quantum computing uses quantum bits (qubits)..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 80,
    "total_tokens": 95
  }
}

レスポンスのステータス

ステータス	説明
completed	生成完了
failed	生成失敗 (error フィールドを参照)
in_progress	生成中 (ストリーミング)
incomplete	途中で停止 (incomplete_details.reason を参照)
cancelled	リクエストがキャンセルされた
queued	処理待ち

使用量 (usage)

フィールド	型	説明
input_tokens	integer	入力で消費したトークン数
output_tokens	integer	生成された出力トークン数
total_tokens	integer	入力と出力の合計
input_tokens_details	object	{ cached_tokens }
output_tokens_details	object	{ reasoning_tokens }

マルチターン会話

レスポンスオブジェクトは保存されないため、毎回のリクエストでそれまでのターンを input に含めて送信してください。モデルが行った function_call も、対応する function_call_output と合わせて含めます。空でない previous_response_id または item_reference 入力アイテム（{ "id": "..." } だけで送ったものも含む）を含むリクエストは 400 unsupported_value で拒否されます。store 自体は受け付けますが、無視されます。ただし、Vercel AI SDK など store: true がデフォルトのクライアントはそれまでのターンを item_reference として送るため、store: false を指定してください。ただし、インライン PDF や記録されたリクエスト本文など、リクエストに含まれる内容が保存される場合はあります。何がどれだけの期間保存されるかはゼロデータリテンションに記載しています。

{
  "model": "google/gemma-4-31b-it",
  "input": [
    { "role": "user", "content": "Explain quantum computing in one paragraph." },
    { "role": "assistant", "content": "Quantum computing uses quantum bits (qubits)..." },
    { "role": "user", "content": "Now explain it to a 5-year-old." }
  ]
}