# POST /v1/responses

OpenAI 新一代"单轮输入 + 流式输出"接口，**Codex CLI** 和较新的 OpenAI SDK 使用。

只用 `/v1/chat/completions` 或 `/v1/messages` 的话，不需要了解这个。

## 端点

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

## 与 chat/completions 的区别

| 维度 | `/v1/chat/completions` | `/v1/responses` |
|---|---|---|
| 输入 | `messages` 数组 | `input` 数组（更像事件流） |
| 工具调用 | `tool_calls` / `tool_messages` | 内置 `function_call` / `function_call_output` 事件 |
| 流事件 | `data: {...}` chunk | 命名事件 `response.output_text.delta` 等 |
| 场景 | 聊天应用 | Codex CLI、Agent 框架 |

## 请求

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

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

### 支持的模型

与 `/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`、`gpt-5.3-codex`。上游返回模型不支持时，relay 会返回明确的 `400`。

## 流式响应

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

非流式返回 `{ response, usage }` 一次性包。

## Function calling / tools

`tools` 字段透传，行为与官方一致：

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

工具结果按官方协议发 `function_call_output`。

## 错误

| HTTP | 含义 |
|---|---|
| **400** | `input` 格式错 / `model` 不在 allowlist |
| **401** | token 无效 |
| **403** | 团队被暂停 |
| **429** | 超限流或超配额 |
| **502** | 上游 OpenAI 抖动 |
| **503** | 上游服务暂时不可用，详见 [服务冷却与重试](/docs/guides/account-cooldown) |

## 什么时候用

- ✅ 用 **Codex CLI**（官方走这个）
- ✅ 最新的 OpenAI Agents SDK
- ❌ 聊天机器人 → 用 [`/v1/chat/completions`](/docs/api/chat-completions)