# Response (Responses API)

OpenAI Responses API-compatible endpoint, passed through to the upstream. Supports both streaming (SSE) and non-streaming responses.

Differences from `/v1/chat/completions`: the request uses `input` instead of `messages` and `max_output_tokens` instead of `max_tokens`; the stream is typed events, ending with a `response.completed` event that carries `usage`.

Any chat model can be called; if the upstream does not support the Responses API, its error is passed through and the request is refunded.
Clients that only support the Responses API (e.g. Codex) can point their base_url directly at this gateway.

## POST /v1/responses

> Response (Responses API)

OpenAI Responses API-compatible endpoint, passed through to the upstream. Supports both streaming (SSE) and non-streaming responses.

Differences from `/v1/chat/completions`: the request uses `input` instead of `messages` and `max_output_tokens` instead of `max_tokens`; the stream is typed events, ending with a `response.completed` event that carries `usage`.

Any chat model can be called; if the upstream does not support the Responses API, its error is passed through and the request is refunded.
Clients that only support the Responses API (e.g. Codex) can point their base_url directly at this gateway.

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `application/json`

- **model** `string` **(required)**  
  Model ID; retrieve the available list via `GET /v1/models`
- **input** `string | object[]` **(required)**  
  Input content. Either a string, or an array of OpenAI Responses input items
- **stream** `boolean` (default: `false`)  
  Whether to enable streaming responses (SSE, typed events)
- **max_output_tokens** `integer`  
  Maximum number of output tokens

### Response

- **id** `string`  
  Response ID
- **object** `string`  
  
- **status** `string`  
  Status, e.g. `completed`
- **output** `object[]`  
  Array of output items (text, image generation calls, etc.)
- **usage** `object`  
  
- **usage.input_tokens** `integer`  
  Number of input tokens
- **usage.output_tokens** `integer`  
  Number of output tokens
- **usage.total_tokens** `integer`  
  Total number of tokens

### Error Codes

- `400`: 
- `401`: 
- `402`: 
- `429`: 
- `502`: