# Responses

Source: https://aiand-docs-staging.pages.dev/api/responses/

```http
POST /v1/responses
```

Generate a model response for a given input. Compatible with the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses/create).

## 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`](/models/catalog/): 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](/errors/#turning-reasoning-off).

### Input types

**Simple string:**

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

**Structured input items:**

```json
{
  "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](/api/files/). 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](/capabilities/vision/#url-requirements).

```json
{
  "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](/api/chat-completions/) (or, under [zero data retention](/organizations/zero-data-retention/), rendered in memory with [its own limits](/organizations/zero-data-retention/#inline-pdfs)); 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

```json
{
  "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](/organizations/zero-data-retention/) lists what is stored and for how long.

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