Responses (OpenAI) — Markdown source

> **AI Agents**: Index `/api/llms.txt` | Full `/api/llms-full-en.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Responses (OpenAI)

Create model replies using the **OpenAI Responses API** shape.

```
POST <BASE_URL>/v1/responses
```

Use this when your client expects OpenAI Responses request/response bodies (tools, reasoning effort, etc.). It shares the same X6.AI API key, routing, quota, and billing as Chat Completions and Messages. For GPT-family models whose upstream is configured as the Responses protocol, this endpoint is same-protocol passthrough.

## Authentication

Required: `Authorization: Bearer <API_KEY>` (same key as `/v1/chat/completions` and `/v1/messages`).

## Request headers

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | Bearer API key |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | Deduplicate within 24 hours per key |
| `Accept-Language` / `X-Locale` | No | Localize some error messages |

## Request body

X6.AI accepts OpenAI Responses JSON and recognizes `model` and `stream`.

```json
{
  "model": "gpt-6-sol-discount",
  "input": "Introduce yourself in one sentence.",
  "stream": false
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `model` | Yes | Model id from `GET /v1/models` |
| `input` | Yes | String or Responses-style input items |
| `stream` | No | `true` for Responses SSE events |
| `tools`, `tool_choice`, `reasoning`, `max_output_tokens`, … | No | Forwarded when the model supports them |

Prefer official OpenAI Responses fields.

## Non-streaming response

Success returns an OpenAI Responses-shaped JSON body (exact fields depend on upstream), for example:

```json
{
  "id": "resp_...",
  "object": "response",
  "model": "gpt-6-sol-discount",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "…"}]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8,
    "total_tokens": 20
  }
}
```

`usage` may include cache fields such as `input_tokens_details.cached_tokens`. Billing follows [Model pricing](./model-pricing.md): four tiers (input / cache read / cache write / output) plus long-context rules.

## Streaming

With `stream: true`, X6.AI returns OpenAI Responses events (e.g. `response.created`, `response.output_text.delta`, `response.completed`). See [Streaming](./streaming.md) for general SSE notes.

## Response headers (X6.AI)

Same as Chat Completions: `X-SNX-Trace-ID`, `X-Request-Id` (same value, for reconciliation), `X-SNX-Model`, `X-SNX-Provider`.

## Errors

Same OpenAI-shaped `{ "error": { "message", "code" } }` as Chat Completions (`code` is typically the HTTP status number). See [Errors](./errors.md).

## Endpoint comparison

| Client / protocol | Endpoint | Typical use |
|-------------------|----------|-------------|
| OpenAI Chat Completions | `POST /v1/chat/completions` | General chat, legacy SDKs |
| OpenAI Responses | `POST /v1/responses` | Responses shape, tools & reasoning |
| Anthropic Messages | `POST /v1/messages` | Anthropic SDK / Claude Code |

All three share the **same X6.AI API key**, routing, quota, and billing.

## Related

- [Chat Completions](./chat-completions.md)
- [Messages (Anthropic)](./messages.md)
- [Model pricing](./model-pricing.md)
- [Authentication](./authentication.md)
- [Errors](./errors.md)