# POST /v1/responses

OpenAI's next-generation "single-turn input + streaming output" API, used by **Codex CLI** and newer OpenAI SDKs.

If you only use `/v1/chat/completions` or `/v1/messages`, you do not need to know about this API.

## Endpoint

```
POST https://relay.4aicode.com/v1/responses
```

## Differences from chat/completions

| Dimension | `/v1/chat/completions` | `/v1/responses` |
|---|---|---|
| Input | `messages` array | `input` array (more like an event stream) |
| Tool calls | `tool_calls` / `tool_messages` | Built-in `function_call` / `function_call_output` events |
| Streaming events | `data: {...}` chunks | Named events such as `response.output_text.delta` |
| Use cases | Chat applications | Codex CLI and agent frameworks |

## Request

```http
POST /v1/responses HTTP/1.1
Host: relay.4aicode.com
Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx
content-type: application/json

{
  "model": "gpt-5.6-terra",
  "input": [
    { "role": "user", "content": "Refactor main.go" }
  ],
  "stream": true
}
```

### Supported Models

Same as `/v1/chat/completions`: `gpt-6-astra`, `gpt-6-sol`, `gpt-6.1-sol`, `gpt-6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, and `gpt-5.3-codex`. If the model is not supported upstream, the relay returns an explicit `400` response.

## Streaming Response

```
event: response.created
data: {"response": {"id": "resp_...", ...}}

event: response.output_text.delta
data: {"delta": "package main\n"}

event: response.output_text.done
data: {}

event: response.completed
data: {"response": {...}, "usage": {...}}
```

Non-streaming requests return a single `{ response, usage }` object.

## Function Calling / Tools

The `tools` field is passed through, with behavior consistent with the official API:

```
event: response.output_item.added
data: {"item": {"type": "function_call", "name": "...", "arguments": "..."}}
```

Send tool results as `function_call_output` according to the official protocol.

## Errors

| HTTP | Meaning |
|---|---|
| **400** | Invalid `input` format / `model` is not on the allowlist |
| **401** | Invalid token |
| **403** | Team suspended |
| **429** | Rate limit or quota exceeded |
| **502** | Upstream OpenAI instability |
| **503** | Upstream services are temporarily unavailable; see [Service Cooldowns and Retries](/docs/en/guides/account-cooldown) |

## When to Use It

- ✅ Using **Codex CLI** (it officially uses this API)
- ✅ Using the latest OpenAI Agents SDK
- ❌ Building a chatbot → use [`/v1/chat/completions`](/docs/en/api/chat-completions)