Responses

POST /v1/responses

Generate a model response for a given input. Compatible with the OpenAI Responses API.

Request body

Parameter	Type	Required	Description
model	string	Yes	Model ID
input	string | array	Yes	Text string (treated as a user message) or array of input items
instructions	string	No	System/developer message prepended to context
stream	boolean	No	Stream as SSE. Default: false
temperature	number	No	Sampling temperature, 0–2
top_p	number	No	Nucleus sampling, greater than 0 and at most 1
max_output_tokens	integer	No	Upper bound on generated tokens
tools	array	No	Function tools the model may call
tool_choice	string | object	No	"none", "auto", "required", or a specific tool
parallel_tool_calls	boolean	No	Allow parallel tool calls
reasoning	object	No	{ "effort": …, "summary": "auto"|"concise"|"detailed" }. effort is checked per model against its reasoning_efforts: a level the model doesn’t list runs at the next listed level up, or the highest, which can cost more than the level you sent, and X-Reasoning-Effort reports it. A value outside the effort vocabulary is a 400.
truncation	string	No	"auto" (truncate to fit context) or "disabled"
metadata	object	No	Key-value pairs for tracking
text	object	No	Text response format config
seed	integer	No	Deterministic sampling seed
stop	string | string[]	No	Up to 4 stop sequences
top_k	integer	No	Top-k sampling (provider-specific)
repetition_penalty	number	No	Repetition penalty (provider-specific)

A model can turn reasoning off only if its levels include none. Setting reasoning.effort to none on a model that does not publish it is a 400. The error text is on Errors.

Input types

Simple string:

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

Structured input items:

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

Input item types:

Type	Description
Message	{ "role": "user"|"assistant"|"developer"|"system", "content": string | content[] }
Function call	{ "type": "function_call", "call_id": "...", "name": "...", "arguments": "..." }
Function call output	{ "type": "function_call_output", "call_id": "...", "output": "..." }

Content types: input_text, input_image, input_file

input_image and input_file accept either an inline URL/base64 (image_url on input_image; file_url or file_data on input_file) or a file_id returned by the Files API. When you reference a file_id, the server resolves the upload to a short-lived presigned URL before forwarding to the model. Inline URLs, and the server_url of an MCP tool, must meet the URL requirements.

{
  "model": "<vision-capable-model>",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Describe this image" },
        { "type": "input_image", "file_id": "file-img123" }
      ]
    }
  ]
}

For PDFs, send input_file with the document’s file_id, or inline as file_data (data:application/pdf;base64,...), which is stored as a document file with the same limits as on Chat Completions (or, under zero data retention, rendered in memory with its own limits); the server rasterizes each page and forwards them as input_image parts (one per page). input_image only accepts purpose: "vision" file_ids. Video and audio uploads aren’t yet routable through /v1/responses — use /v1/chat/completions for those.

Response

{
  "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
  }
}

Response status

Status	Description
completed	Generation finished
failed	Generation failed (see error field)
in_progress	Still generating (streaming)
incomplete	Stopped early (see incomplete_details.reason)
cancelled	Request was cancelled
queued	Waiting to be processed

Usage

Field	Type	Description
input_tokens	integer	Input tokens consumed
output_tokens	integer	Output tokens generated
total_tokens	integer	Sum of input and output tokens
input_tokens_details	object	{ cached_tokens }
output_tokens_details	object	{ reasoning_tokens }

Multi-turn conversations

Response objects are not stored, so send the earlier turns in input on every request, including each function_call the model made alongside its function_call_output. A request with a non-empty previous_response_id or an item_reference input item, including one sent as just { "id": "..." }, is rejected with 400 unsupported_value. store itself is accepted and ignored, but clients that default to store: true, such as the Vercel AI SDK, send earlier turns as item_reference, so set store: false on them. Content a request carries may still be stored, such as an inline PDF or a logged request body; Zero data retention lists what is stored and for how long.

{
  "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." }
  ]
}