OpenAI Responses

# OpenAI Responses 调用文档

Responses 接口采用 OpenAI Responses 协议，通过 `input` 提交输入内容，通过 `output` 返回生成结果，支持非流式响应和 SSE 流式响应。

本文示例模型为 `qwen3.7-plus`。

## 接口信息

| 项目     | 内容                                   |
| -------- | -------------------------------------- |
| 基础地址 | `https://aiproxy-api.cloudcare.cn`     |
| 请求方法 | `POST`                                 |
| 接口路径 | `/v1/responses`                        |
| 鉴权     | `Authorization: Bearer <平台 API Key>` |
| 请求类型 | `Content-Type: application/json`       |

调用示例使用环境变量 `AIPROXY_API_KEY` 传递平台 API Key。请将 `YOUR_API_KEY` 替换为实际密钥。

```bash
export AIPROXY_API_KEY='YOUR_API_KEY'
```

## 非流式调用

### 请求示例

```bash
curl 'https://aiproxy-api.cloudcare.cn/v1/responses' \
  -H "Authorization: Bearer ${AIPROXY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3.7-plus",
    "instructions": "你是一个专业的技术助手，请使用中文回答。",
    "input": "简要解释什么是可观测性。",
    "stream": false
  }'
```

### 响应示例

以下为响应主要字段示例，内容及用量数值仅供参考。

```json
{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "model": "qwen3.7-plus",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {"type": "output_text", "text": "可观测性是通过系统输出理解其内部状态的能力。", "annotations": []}
      ]
    }
  ],
  "usage": {"input_tokens": 30, "output_tokens": 40, "total_tokens": 70}
}
```

回复文本位于 `output` 中类型为 `message` 的条目内，通过 `content` 中类型为 `output_text` 的 `text` 字段返回。客户端应按条目类型遍历输出。

## 请求参数

| 参数                   | 类型            | 必填 | 说明                                                 |
| ---------------------- | --------------- | ---- | ---------------------------------------------------- |
| `model`                | string          | 是   | 已开通 Responses 协议的模型名称                      |
| `input`                | string 或 array | 是   | 单轮文本或包含历史消息的输入列表                     |
| `instructions`         | string          | 否   | 本次请求的系统指令                                   |
| `stream`               | boolean         | 否   | `true` 开启 SSE                                      |
| `max_output_tokens`    | integer         | 否   | 最大输出 Token 预算，具体支持以模型为准              |
| `temperature`          | number          | 否   | 采样随机性，需模型支持                               |
| `tools`                | array           | 否   | 工具定义，需模型及渠道支持                           |
| `tool_choice`          | string / object | 否   | 自动、禁止或指定工具调用等策略                       |
| `text.format`          | object          | 否   | 文本输出格式或 JSON Schema                           |
| `reasoning`            | object          | 否   | 推理设置，可用字段及取值由模型决定                   |
| `previous_response_id` | string          | 否   | 引用之前的响应，依赖上游状态与路由支持               |
| `store`                | boolean         | 否   | 请求上游是否存储响应；不控制平台调用记录和摘要的保存 |

请求参数及流式事件采用 Responses 协议结构。与 Chat Completions 的字段对应关系见本文字段对照表。

## 流式调用

### 请求示例

```bash
curl -N 'https://aiproxy-api.cloudcare.cn/v1/responses' \
  -H "Authorization: Bearer ${AIPROXY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3.7-plus",
    "input": "介绍日志、指标和链路追踪的区别。",
    "stream": true
  }'
```

### 响应示例

以下为主要 SSE 事件，省略事件序号及部分元数据。

```text
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"日志记录"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"离散事件。"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_example","status":"completed","usage":{"input_tokens":20,"output_tokens":30,"total_tokens":50}}}
```

拼接 `response.output_text.delta` 事件中的 `delta`。正常结束时处理 `response.completed`，并读取最终响应的用量；同时处理 `response.failed`、`response.incomplete` 和错误事件，不能把连接断开直接视为成功。事件语义参见 [OpenAI 流式响应文档](https://developers.openai.com/api/docs/guides/streaming-responses)。

## 多轮对话

通过 `input` 列表按时间顺序传入历史消息和当前问题。请求体示例：

```json
{
  "model": "qwen3.7-plus",
  "instructions": "请用简洁的中文回答。",
  "input": [
    {"role": "user", "content": "什么是可观测性？"},
    {"role": "assistant", "content": "可观测性是通过系统输出理解其内部状态的能力。"},
    {"role": "user", "content": "给出一个订单服务的应用例子。"}
  ],
  "stream": false
}
```

包含工具调用的对话应保留工具调用记录，并按协议回传执行结果。

`previous_response_id` 用于引用历史响应，适用范围取决于上游响应存储及路由配置。客户端也可通过 `input` 显式管理对话历史。

## 结构化输出

通过 `text.format` 指定 JSON Schema。以下示例适用于支持结构化输出的模型。

```json
{
  "model": "qwen3.7-plus",
  "input": "订单服务发生超时，请提取服务名和问题摘要。",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "alert_summary",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "service": {"type": "string"},
          "summary": {"type": "string"}
        },
        "required": ["service", "summary"],
        "additionalProperties": false
      }
    }
  }
}
```

结构化结果以 JSON 字符串形式返回于 `output` 的文本内容中，由客户端解析。Schema 支持范围及拒绝响应处理参见 [OpenAI Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)。

## 工具调用

### 声明工具

在 `tools` 数组中声明函数名称、描述及参数结构。以下示例适用于支持工具调用的模型。

```json
{
  "model": "qwen3.7-plus",
  "input": "查询订单 A1001 的状态。",
  "tools": [{
    "type": "function",
    "name": "lookup_order",
    "description": "根据订单编号查询订单状态",
    "parameters": {
      "type": "object",
      "properties": {"order_id": {"type": "string"}},
      "required": ["order_id"],
      "additionalProperties": false
    },
    "strict": true
  }],
  "tool_choice": "auto"
}
```

### 返回工具执行结果

读取 `output` 中类型为 `function_call` 的条目，根据 `name`、`arguments` 和 `call_id` 校验并执行函数。后续请求的 `input` 应包含原始输入、上一轮完整 `output` 及以下工具结果条目：

```json
{
  "type": "function_call_output",
  "call_id": "call_order_001",
  "output": "{\"status\":\"shipped\"}"
}
```

上述对象为 `input` 数组中的工具结果条目，`call_id` 应使用实际响应值。保留上一轮的推理项及其他输出项，继续调用工具时保留工具定义。模型可能要求多个工具调用，应逐项返回结果。参见 [OpenAI Function Calling](https://developers.openai.com/api/docs/guides/function-calling)。

## 图片输入

图片输入使用 `input` 中的多模态内容数组，适用于支持图片理解的模型。请求体示例：

```json
{
  "model": "qwen3.7-plus",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "描述这张图片。"},
      {"type": "input_image", "image_url": "https://example.com/image.jpg"}
    ]
  }]
}
```

`input_image.image_url` 为图片地址字符串。请将示例 URL 替换为可访问的实际图片地址。参见 [OpenAI Images and Vision](https://developers.openai.com/api/docs/guides/images-vision)。

## 流式事件与响应状态

| 事件                                      | 用途                             |
| ----------------------------------------- | -------------------------------- |
| `response.created`                        | 响应已创建，不代表生成完成       |
| `response.output_item.added`              | 新增输出项，可能是消息或工具调用 |
| `response.output_text.delta`              | 文本增量，按输出项及内容索引拼接 |
| `response.output_text.done`               | 某段文本完成，整次响应仍可能继续 |
| `response.function_call_arguments.delta`  | 工具参数增量，完整后再解析       |
| `response.completed`                      | 响应正常完成，读取最终状态和用量 |
| `response.incomplete` / `response.failed` | 生成未完成或失败，检查原因       |
| `error`                                   | 流内错误                         |

客户端应组装完整 SSE 事件后，根据 JSON 的 `type` 字段处理事件，并记录响应 ID。响应结束状态由 Responses 终态事件确定。事件说明见 [OpenAI 流式响应文档](https://developers.openai.com/api/docs/guides/streaming-responses)。

非流式响应通过 `status` 表示生成状态。状态为 `incomplete` 时检查 `incomplete_details`，失败时检查 `error`；输出中的拒绝内容应按相应条目类型处理。

## 与 Chat Completions 的字段对照

| 用途         | Chat Completions                                  | Responses                             |
| ------------ | ------------------------------------------------- | ------------------------------------- |
| 输入         | `messages`                                        | `input`                               |
| 系统指令     | system 消息                                       | `instructions` 或相应输入消息         |
| 输出文本     | `choices[].message.content`                       | `output[].content[]` 的 `output_text` |
| 输出预算     | `max_completion_tokens` 或渠道支持的 `max_tokens` | `max_output_tokens`                   |
| 结构化输出   | `response_format`                                 | `text.format`                         |
| 工具定义     | `tools[].function`                                | `tools[]` 中直接声明函数字段          |
| 工具结果     | `role: tool` 和 `tool_call_id`                    | `function_call_output` 和 `call_id`   |
| 输入输出用量 | `prompt_tokens` / `completion_tokens`             | `input_tokens` / `output_tokens`      |

Responses 的整体对象模型见 [官方 Responses 概览](https://developers.openai.com/api/reference/responses/overview)。

## 用量统计与接口范围

- `usage.input_tokens`、`output_tokens`、`total_tokens` 分别表示输入、输出和总 Token 用量。
- 本文说明 `POST /v1/responses` 创建接口。响应检索、删除、后台任务及内置工具不属于本文接口范围。
- 对话续接可使用稳定的 `session-id` 请求头辅助会话亲和，但仍需提供所需上下文。
- 请求超时取决于平台部署和上游配置。

`usage.input_tokens_details.cached_tokens` 和 `usage.output_tokens_details.reasoning_tokens` 为可选用量明细，已包含在相应 Token 统计中，无需重复累加。

## 错误处理

错误码及处理方式请参阅 [错误响应汇总](https://mrdoc.cloudcare.cn/doc/1042/)。