# 创建 Response

使用 Responses 请求形态向支持该接口的 Genesis 模型发送输入，并从 `output[]` 读取结果。本页只说明最小的非流式请求；状态、会话和工具能力仅在当前模型及服务配置明确支持时使用。

```text
POST https://token.moi.matrixorigin.cn/v1/responses
```

## 调用前准备

请求地址为 `https://token.moi.matrixorigin.cn/v1/responses`。准备具有 Genesis 权限的访问凭据，以及支持 Responses 的模型 ID。

下方示例使用：

- `$GENESIS_ACCESS_TOKEN`：实际访问令牌或服务账号 API Key，通过 `Authorization` Header 传递。
- `$MODEL_ID`：要调用的模型 ID，填入请求体的 `model` 字段。

## 请求头

| 请求头 | 是否必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | 使用 `Bearer <GENESIS_ACCESS_TOKEN>` 传递访问凭据。 |
| `Content-Type` | 是 | 设置为 `application/json`。 |

## 请求体

请求体包含以下字段。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 支持 Responses 的模型 ID。 |
| `input` | string 或 array | 是 | 本次输入。最小请求可使用字符串。 |
| `instructions` | string | 否 | 本次请求的附加指令。 |
| `store` | boolean | 否 | 是否保存本次 Response。调试或一次性调用可显式设为 `false`。 |
| `stream` | boolean | 否 | 是否请求 Responses 原生 SSE 事件。其事件结构不能按 Chat Completions 解析；非流式调用请显式设为 `false`。 |
| `temperature` | number | 否 | 采样温度。仅使用目标模型支持的范围。 |
| `top_p` | number | 否 | 核采样参数。仅使用目标模型支持的范围。 |
| `max_output_tokens` | integer | 否 | 输出 Token 上限。使用目标模型支持的值。 |

不要将 Chat Completions 的 `messages` 用作 Responses 的输入，也不要从 `choices[]` 读取结果。

使用从[查询模型列表](models.md)返回的模型 ID。是否支持 Responses 及其可选参数，以实际模型支持范围为准。

## 请求示例

```bash
curl -X POST "https://token.moi.matrixorigin.cn/v1/responses" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "input": "用一句话说明索引的作用。",
    "store": false,
    "stream": false,
    "temperature": 0.7,
    "top_p": 0.9,
    "max_output_tokens": 2048,
    "instructions": "You are a concise API debugging assistant."
  }'
```

实际业务可按模型能力调整可选参数。

## 成功响应

成功响应的业务结果位于 `output[]`：

```json
{
  "id": "<RESPONSE_ID>",
  "object": "response",
  "status": "completed",
  "model": "<MODEL_ID>",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "索引通过建立可快速定位的数据结构来减少查询扫描范围。"
        }
      ]
    }
  ]
}
```

响应中用于读取结果的字段如下。

字段路径中的 `[]` 表示数组中的每一项。例如，`output[].content[].text` 表示 `output` 数组中每一项的 `content` 数组中每一项的 `text` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 本次 Response 的标识。 |
| `object` | string | 响应对象类型，示例为 `response`。 |
| `status` | string | 当前响应状态。存在输出时再读取对应内容。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `output` | array | 输出项列表。 |
| `output[].type` | string | 输出项类型，例如 `reasoning` 或 `message`。 |
| `output[].content` | array | `message` 输出项中的内容块列表；其他输出项可能没有该字段。 |
| `output[].content[].type` | string | 内容块类型。 |
| `output[].content[].text` | string | `content[].type` 为 `output_text` 时的生成文本。 |

`output[]` 可以先返回 `reasoning`，再返回包含 `output_text` 的 `message`。应用应遍历全部输出项并检查 `type`，不要按数组第一项读取文本。

## 错误响应

接口不使用 `code`、`msg`、`data` 包络。收到非成功 HTTP 状态时，不要从 `output[]` 读取结果。错误对象由兼容的模型服务返回；除 `error.message` 外的字段可能省略。

### 错误对象字段

```json
{
  "error": {
    "message": "<可读错误信息>",
    "type": "<错误类型，可能省略>",
    "code": "<错误代码，可能省略>"
  }
}
```

错误正文中可能出现的字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error.message` | string | 可读错误信息。 |
| `error.type` | string，可选 | 上游错误类别。 |
| `error.code` | string 或 null，可选 | 上游错误代码。 |

### 常见 HTTP 错误

下表说明收到不同 HTTP 状态时应执行的操作。

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - —
  - `input`、模型 ID 或可选参数不符合接口要求。
  - 先仅发送 `model` 与字符串 `input`。
* - `401`
  - —
  - 凭据无效，或当前凭据无权调用该模型。
  - 检查认证 Header 和模型范围。
* - `403`
  - —
  - 凭据无效，或当前凭据无权调用该模型。
  - 检查认证 Header 和模型范围。
* - `429`
  - —
  - 当前请求受到限制。
  - 降低请求频率后再提交请求。
* - `5xx`
  - —
  - 服务或依赖暂时无法处理请求。
  - 稍后再次提交请求。
```

## 后续操作

- [查询模型列表](models.md)
- [Chat Completions](chat-completions.md)