# Responses API

使用 Responses API 发送 OpenAI Responses 形态的请求，并从 `output[]` 读取结果。它与 Chat Completions 使用不同的请求和响应对象；完成本页后，你将发送一次无状态请求，读取模型输出，并识别只在特定模型或配置下可用的扩展能力。

## 前提条件

- 已从[获取可用模型](../getting-started/available-models.md)取得支持 Responses 调用形态的模型 ID。
- 已按[身份认证](../getting-started/authentication.md)配置访问令牌。

## 请求地址

```text
POST <GENESIS_BASE_URL>/responses
```

## 发送无状态请求

最小请求使用 `model` 和 `input`。`input` 可以是字符串，也可以是符合 Responses 形态的消息或输入项数组；下面先使用字符串完成一次最小验证：

```bash
curl -X POST "$GENESIS_BASE_URL/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -d '{
    "model": "<RESPONSES_MODEL_ID>",
    "input": "写一句关于数据库可靠性的短句。"
  }'
```

成功后，从 `output[]` 读取响应内容。不要使用 Chat Completions 的 `messages` 构造请求，也不要从 `choices[]` 读取结果。

## 请求参数

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 支持 Responses 调用形态的模型 ID。调用前从当前凭证可用模型中确认。 |
| `input` | string 或 array | 是 | 输入内容。可传字符串，或符合当前 Responses 接口说明的消息/输入项数组。 |
| `instructions` | string | 否 | 系统级指令。需要将通用指令与本次输入分开时使用。 |
| `stream` | boolean | 否 | 控制返回完整响应还是 Responses 的 SSE 事件。Responses 的事件格式与 Chat Completions 不同。 |
| `store` | boolean | 否 | 是否保存响应状态。仅在当前模型和服务配置支持有状态 Responses 时使用。 |
| `previous_response_id` | string | 否 | 用于续接此前响应的标识。仅在当前模型和服务配置支持时使用。 |
| `conversation` | string 或 object | 否 | 会话标识或包含标识的会话对象。仅在当前模型和服务配置支持时使用。 |
| `tools` | array | 否 | 工具定义或 Provider 内置工具配置。支持情况由模型和当前服务配置共同决定。 |

首次接入时只发送 `model` 和 `input`。需要状态、会话或工具调用时，先在控制台确认所选模型的当前示例，再为该能力发送最小请求验证。不能因为某个 Chat Completions 模型支持工具调用，就假定它同样支持 Responses 工具调用。

## 成功响应

Responses 的业务结果位于 `output[]`。下例展示一个包含文本输出项的响应：

```json
{
  "id": "<response-id>",
  "object": "response",
  "created_at": 0,
  "status": "completed",
  "model": "<RESPONSES_MODEL_ID>",
  "output": [
    {
      "id": "<output-item-id>",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "可靠的数据库让关键业务在故障中也能持续运行。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}
```

| 字段 | 类型 | 返回条件 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 成功响应返回 | 本次响应的标识。排查调用问题时提供该值。 |
| `object` | string | 成功响应返回 | 响应对象类型。 |
| `status` | string | 当前响应包含时 | 响应状态。只有状态表明已完成且存在相应输出时，才读取结果。 |
| `model` | string | 成功响应返回 | 实际处理本次请求的模型 ID。 |
| `output` | array | 当前响应包含输出项时 | Responses 输出项列表。不要按 Chat Completions 的 `choices[]` 解析。 |
| `output[].content[].text` | string | 输出项包含 `output_text` 时 | 模型生成的文本内容。 |
| `usage` | object | 当前响应包含时 | 本次请求的 Token 用量信息。只读取实际返回的字段。 |

`output[]` 可以包含不同类型的输出项。应用应根据每项的 `type` 和 `content[].type` 处理返回内容，而不是假定每个响应都只含一段文本。

## 使用流式、状态和工具能力

将 `stream` 设为 `true` 后，服务返回 Responses 原生 SSE 事件。不要复用[Chat Completions 流式输出](chat-completions/streaming-chat-completions.md)中 Chat Completions 的 `choices[].delta.content` 解析逻辑；应以当前控制台提供的 Responses 事件示例为准。

有状态调用、会话和工具能力不是所有模型的共同能力。当前模型或服务配置不支持时，相关参数或状态操作可能返回不支持错误。先保持无状态请求成功，再逐项验证所需扩展能力。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 结果中没有 `choices[]` | 是否将 Responses 响应按 Chat Completions 处理 | 从 `output[]` 读取输出项，并按其类型解析内容。 |
| 请求被拒绝或模型不可用 | `model` 是否支持 Responses，以及 `GET /models` 的结果 | 选择当前凭证可访问且支持 Responses 的模型，先发送无状态最小请求。 |
| 服务端返回 `5xx` | HTTP 状态码、错误消息、`model` 值，以及是否仅发送了 `model` 和 `input` | 使用无状态最小请求重试；持续失败时，更换另一已验证的 Responses 模型，并提供脱敏后的状态码、错误消息和模型 ID 进行排查。 |
| 使用状态或工具参数后失败 | 当前模型和控制台是否展示对应能力 | 移除扩展参数恢复最小请求，再逐项验证所需能力。 |
| 流式解析失败 | 是否使用了 Chat Completions 的 SSE 字段路径 | 按当前 Responses 事件示例解析，不要读取 `choices[].delta.content`。 |
| 认证失败 | 请求地址、令牌和 `Authorization` Header | 按[身份认证](../getting-started/authentication.md)重新配置当前环境的凭据。 |

## 下一步

- [查看当前凭证可用的模型](../getting-started/available-models.md)
- [选择支持 Responses 的模型](../getting-started/choose-model-capabilities.md)
- [查看文本对话调用方式](chat-completions/text-chat.md)