# Responses

Source: https://staging-docs.aiand.com/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, 0–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": "low"\|"medium"\|"high", "summary": "auto"\|"concise"\|"detailed" }` |
| `truncation` | string | No | `"auto"` (truncate to fit context) or `"disabled"` |
| `previous_response_id` | string | No | Continue a multi-turn conversation |
| `store` | boolean | No | Store the response for later retrieval |
| `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) |

### Input types

**Simple string:**

```json
{
  "model": "openai/gpt-oss-120b",
  "input": "Explain quantum computing in one paragraph."
}
```

**Structured input items:**

```json
{
  "model": "openai/gpt-oss-120b",
  "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 output | `{ "type": "function_call_output", "call_id": "...", "output": "..." }` |
| Item reference | `{ "type": "item_reference", "id": "..." }` |

**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.

```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`; 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": "openai/gpt-oss-120b",
  "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

Use `previous_response_id` to continue a conversation without resending the full history:

```json
{
  "model": "openai/gpt-oss-120b",
  "input": "Now explain it to a 5-year-old.",
  "previous_response_id": "resp_abc123"
}
```

Stored responses are private to the API key's user within their organization. A `previous_response_id` (or an `item_reference`) created by a different user or organization — or that doesn't exist — returns `404 Not Found`.