# 创建响应（OpenAI Responses）

> BigModel.io 的 POST /v1/responses 接口：Codex CLI 使用的 OpenAI Responses 协议，支持流式和工具。每轮都要发送完整 input，HTTP 方式不支持 previous_response_id。

网页版: https://bigmodel.io/zh-cn/docs/api-responses · 更新于 2026-10-18

`POST https://bigmodel.io/v1/responses`

OpenAI Responses 接口，[Codex CLI](https://bigmodel.io/zh-cn/docs/codex-cli) 使用的就是它。OpenAI 分组原生提供，Anthropic 分组转换处理；仅对话补全分组（DeepSeek、GLM 平台）返回 `404`。HTTP 方式下网关不保存会话状态：带 `previous_response_id` 会返回 `400`，每轮都要在 `input` 里带上完整对话。

## 请求

```http
POST https://bigmodel.io/v1/responses
```

### 认证

| 请求头 | 值 |
|---|---|
| `Authorization` | `Bearer $BIGMODEL_API_KEY` |
| `x-api-key` | `$BIGMODEL_API_KEY` |

任选其一。

### 请求体

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型 ID。 |
| `input` | string \| array<object> |  | 文本或输入项数组。 |
| `instructions` | string |  | 系统指令。 |
| `stream` | boolean |  | 如提供必须是布尔值。 |
| `tools` | array<object> |  |  |
| `reasoning` | object |  |  |
| `reasoning.effort` | string |  |  |
| `previous_response_id` | string |  | HTTP 方式不支持（返回 400），请在 `input` 中带上完整对话。 |

## 响应

| 状态码 | 含义 |
|---|---|
| `200` | 响应对象；`stream` 为 true 时为 Responses SSE 事件流。 |
| `400` | `api_key_in_query_deprecated`（Key 放在了查询参数里），或 `invalid_request_error`：请求体为空或不是合法 JSON、缺少 `model`、`stream` 不是布尔值等。 |
| `401` | `API_KEY_REQUIRED`、`INVALID_API_KEY`、`API_KEY_DISABLED`、`USER_NOT_FOUND`、`USER_INACTIVE`。 |
| `403` | `INSUFFICIENT_BALANCE`、`API_KEY_EXPIRED`、`ACCESS_DENIED`（IP 规则）、`SUBSCRIPTION_NOT_FOUND`、`SUBSCRIPTION_INVALID`，或 `permission_error`（Key 未分配分组、分组不允许该接口）。 |
| `404` | `not_found_error`：该 Key 所在分组只提供 `/v1/chat/completions`。 |
| `413` | 请求体过大。 |
| `429` | `API_KEY_QUOTA_EXHAUSTED`、`USAGE_LIMIT_EXCEEDED`（套餐额度），或 `rate_limit_exceeded` / `rate_limit_error`（Key 的 5 小时/1 天/7 天限额、每分钟请求数、并发、上游限流）。每分钟限流会带 `Retry-After`。 |
| `502` | `upstream_error`：模型服务商出错。 |
| `503` | `api_error` 等：分组暂时没有该模型的可用容量，或分组不提供该模型（`No available accounts`）。 |

`stream: true` 时返回 Responses 事件流（`response.created`、`response.output_text.delta` …… `response.completed`）。


## 示例

```bash [cURL]
curl https://bigmodel.io/v1/responses \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "instructions": "你是一个简洁的助手。",
    "input": "用一句话解释 HTTP 429。"
  }'
```

```python [Python]
import os
from openai import OpenAI

client = OpenAI(base_url="https://bigmodel.io/v1", api_key=os.environ["BIGMODEL_API_KEY"])

resp = client.responses.create(
    model="glm-5.3",
    instructions="你是一个简洁的助手。",
    input="用一句话解释 HTTP 429。",
)
print(resp.output_text)
```

```js [Node.js]
import OpenAI from 'openai'

const client = new OpenAI({baseURL: 'https://bigmodel.io/v1', apiKey: process.env.BIGMODEL_API_KEY})

const resp = await client.responses.create({
  model: 'glm-5.3',
  instructions: '你是一个简洁的助手。',
  input: '用一句话解释 HTTP 429。',
})
console.log(resp.output_text)
```

响应示例，只保留标准 Responses 对象的主要字段（`id`、文本和 token 数仅作示意）：

```json
{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "glm-5.3",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "HTTP 429 表示你在一段时间内请求过多，需要稍后重试。"}]
    }
  ],
  "usage": {"input_tokens": 21, "output_tokens": 19, "total_tokens": 40}
}
```

### 不用 previous_response_id 的多轮对话

```python [Python]
history = [{"role": "user", "content": "我叫小安。"}]
first = client.responses.create(model="glm-5.3", input=history)

history += [
    {"role": "assistant", "content": first.output_text},
    {"role": "user", "content": "我叫什么？"},
]
second = client.responses.create(model="glm-5.3", input=history)
print(second.output_text)
```

## 说明

- **HTTP 方式不支持 `previous_response_id`**，会返回 `400` `invalid_request_error`（"previous_response_id is only supported on Responses WebSocket v2"）。请自己保存历史并每次重发，如上例。`GET /v1/responses` 是 WebSocket 通道，不带 `Upgrade` 请求头时返回 `426`。
- **`stream` 如提供必须是布尔值**，否则返回 `400`（"invalid stream field type"）。
- **仅对话补全分组返回 `404`。** 这类 Key 请使用[对话补全](https://bigmodel.io/zh-cn/docs/api-chat-completions)。
- **模型不存在返回 `503`** `api_error`（"No available accounts"），不是 `404`。
- **错误结构。** OpenAI 分组返回 `{"error":{"type","message"}}`；Anthropic 分组上本接口的错误形如 `{"error":{"code","message"}}`。Key 检查阶段使用 `{"code","message"}`。流式过程中的错误以 SSE `error` 事件返回。完整列表见[错误码](https://bigmodel.io/zh-cn/docs/errors)。

## 相关文档

- [Codex CLI](https://bigmodel.io/zh-cn/docs/codex-cli)
- [流式输出](https://bigmodel.io/zh-cn/docs/streaming)
- [推理与思考](https://bigmodel.io/zh-cn/docs/reasoning)