Responses（OpenAI） — Markdown 源文

> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Responses（OpenAI）

使用 **OpenAI Responses API** 格式创建模型回复。

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

适用于期望 OpenAI Responses 请求/响应形态的客户端（工具调用、推理 effort 等）。与 Chat Completions、Messages 共用同一 X6.AI API Key、路由、配额与计费。部分 GPT 族模型在上游配置为 Responses 协议时，本端点为同协议透传。

## 认证

必需：`Authorization: Bearer <API_KEY>`（与 `/v1/chat/completions`、`/v1/messages` 相同）。

## 请求头

| 头 | 必需 | 说明 |
|----|------|------|
| `Authorization` | 是 | Bearer API Key |
| `Content-Type` | 是 | `application/json` |
| `Idempotency-Key` | 否 | 24 小时内按 Key 去重 |
| `Accept-Language` / `X-Locale` | 否 | 部分错误文案本地化 |

## 请求体

X6.AI 接受 OpenAI Responses JSON，识别 `model` 与 `stream`。

```json
{
  "model": "gpt-6-sol-discount",
  "input": "用一句话介绍你自己。",
  "stream": false
}
```

| 字段 | 必需 | 说明 |
|------|------|------|
| `model` | 是 | `GET /v1/models` 返回的模型 id |
| `input` | 是 | 字符串或 Responses 形态的 input items |
| `stream` | 否 | `true` 时返回 Responses SSE 事件流 |
| `tools`、`tool_choice`、`reasoning`、`max_output_tokens` 等 | 否 | 按 OpenAI Responses 兼容方式原样转发（如模型支持） |

也可使用带角色的 messages 风格输入（视上游与网关转换而定）；优先以 OpenAI Responses 官方字段为准。

## 非流式响应

成功时返回 OpenAI Responses 形态 JSON（字段以实际上游为准），例如：

```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` 可能含 `input_tokens_details.cached_tokens` 等缓存字段；计费按 [模型定价](./model-pricing.md) 四档（输入 / 缓存读取 / 缓存写入 / 输出）及长上下文规则。

## 流式

`stream: true` 时返回 OpenAI Responses 事件流（如 `response.created`、`response.output_text.delta`、`response.completed`）。通用 SSE 说明见 [流式响应](./streaming.md)。

## 响应头（X6.AI）

与 Chat Completions 相同：`X-SNX-Trace-ID`、`X-Request-Id`（同值，便于对账）、`X-SNX-Model`、`X-SNX-Provider`。

## 错误格式

与 Chat Completions 相同，返回 OpenAI 形态 `{ "error": { "message", "code" } }`（`code` 多为 HTTP 状态码数字）。详见 [错误处理](./errors.md)。

## 三端点对照

| 客户端 / 协议 | 端点 | 典型用途 |
|---------------|------|----------|
| OpenAI Chat Completions | `POST /v1/chat/completions` | 通用对话、兼容旧 SDK |
| OpenAI Responses | `POST /v1/responses` | Responses 形态、工具与推理 |
| Anthropic Messages | `POST /v1/messages` | Anthropic SDK / Claude Code |

三者共用 **同一 X6.AI API Key**，路由、配额与计费逻辑一致。

## 相关

- [Chat Completions](./chat-completions.md)
- [Messages（Anthropic）](./messages.md)
- [模型定价](./model-pricing.md)
- [认证](./authentication.md)
- [错误处理](./errors.md)