> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses

> POST /v1/responses —— OpenAI 新版统一响应接口

`/v1/responses` 是 OpenAI 推出的新版接口,用统一的响应对象管理多步对话与工具调用,适合 Agent 场景。

<Info>OpenAI 现已将 **Responses API 作为推荐的首选接口**,新项目建议优先使用它;Chat Completions 仍长期保留并向后兼容。</Info>

## 与 chat/completions 的区别

| 维度   | `/v1/chat/completions` | `/v1/responses`                                  |
| ---- | ---------------------- | ------------------------------------------------ |
| 输入   | `messages` 数组          | `input`(可为字符串、消息数组或 `previous_response_id`)      |
| 状态   | 无状态,每次需传完整历史           | 可选有状态(`store: true`)                             |
| 工具   | `tools` + `tool_calls` | 内置 `web_search`、`file_search`、`code_interpreter` |
| 模型范围 | 所有模型                   | 主要 OpenAI 新模型                                    |

## 请求

```bash theme={null}
curl https://openp.ai/v1/responses \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "用 200 字介绍 OpenPAI"
  }'
```

### 主要参数

| 字段                      | 类型               | 说明                        |
| ----------------------- | ---------------- | ------------------------- |
| `model`                 | string           | 模型 ID                     |
| `input`                 | string \| array  | 输入内容,支持纯文本或多模态数组          |
| `instructions`          | string           | 等价 system prompt          |
| `previous_response_id`  | string           | 接续之前的响应,无需重传历史            |
| `tools`                 | array            | 内置工具或自定义函数                |
| `tool_choice`           | string \| object | 工具选择策略                    |
| `stream`                | boolean          | 流式输出                      |
| `store`                 | boolean          | 是否在服务端保存对话状态              |
| `temperature` / `top_p` | number           | 采样参数                      |
| `max_output_tokens`     | integer          | 最大输出 token                |
| `reasoning`             | object           | `{ effort: "high" }` 推理强度 |
| `metadata`              | object           | 业务标签                      |
| `user`                  | string           | 终端用户标识                    |

## 响应

```json theme={null}
{
  "id": "resp_...",
  "object": "response",
  "created_at": 1715750400,
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "OpenPAI 是一个..."}]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 48,
    "total_tokens": 60,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens_details": { "reasoning_tokens": 0 }
  }
}
```

可通过 `response.output_text`(SDK 辅助字段)直接取到合并后的文本。

## 多轮对话

第二轮无需重传历史,使用 `previous_response_id`:

```json theme={null}
{
  "model": "gpt-5.5",
  "previous_response_id": "resp_...",
  "input": "再展开第 2 点"
}
```

需要先在第一次请求中传入 `store: true` 以让 OpenPAI 保留状态。

## 推理

```json theme={null}
{
  "model": "o3-mini",
  "input": "证明 √2 是无理数",
  "reasoning": { "effort": "high" },
  "max_output_tokens": 4096
}
```

## 内置工具

```json theme={null}
{
  "model": "gpt-5.5",
  "input": "最新的 OpenPAI 新闻",
  "tools": [{ "type": "web_search" }]
}
```

支持的内置工具(以上游可用为准):

* `web_search` —— 联网搜索
* `file_search` —— 在已上传文件中检索
* `code_interpreter` —— 在沙箱中执行代码

部分内置工具依赖上游环境,OpenPAI 透传调用结果。