# Responses

向支持 Responses 的 Genesis 模型提交输入，并从返回的输出项中取得生成文本。

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

## 调用前准备

准备具有 Genesis 权限的访问凭据。选择支持 Responses 的模型；可从[查看模型列表](../models.md)取得模型 ID。

## 请求体

将 `$GENESIS_ACCESS_TOKEN` 替换为访问令牌或服务账号 API Key，将 `$MODEL_ID` 替换为所选模型的 ID。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```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."
  }'
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 要调用的 Responses 模型 ID。 |
| `input` | string | 是 | 本次请求的文本输入。 |
| `store` | boolean | 否 | 是否保存本次 Response。 |
| `stream` | boolean | 否 | 是否请求 Responses 原生 SSE 事件。 |
| `temperature` | number | 否 | 采样温度。 |
| `top_p` | number | 否 | 核采样参数。 |
| `max_output_tokens` | integer | 否 | 输出 Token 上限。 |
| `instructions` | string | 否 | 本次请求的附加指令。 |

:::::
::::::
:::::::

## 成功响应

服务返回本次 Response 的标识、状态和输出项。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 本次 Response 的标识。 |
| `object` | string | 响应对象类型，示例为 `response`。 |
| `status` | string | 当前响应状态。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `output` | array of object | 输出项列表。 |

:::
:::{tab-item} 输出项

下面表格展开示例中 `output` 数组的每一项；每一行是该数组项的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | string | 输出项类型，例如 `reasoning` 或 `message`。 |
| `role` | string | 消息输出项的角色，示例为 `assistant`。 |
| `content` | array of object | 消息输出项的内容块列表。 |

:::
:::{tab-item} 内容项

下面表格展开示例中 `output[].content` 数组的每一项；每一行是该数组项的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | string | 内容块类型。 |
| `text` | string | `type` 为 `output_text` 时的生成文本。 |

:::
::::

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error` | object | 错误对象。 |

:::
:::{tab-item} 错误对象

下面表格展开示例中 `error` 对象；每一行是该对象的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `message` | string | 可读错误信息。 |
| `type` | string | 模型服务返回的错误类别，可能省略。 |
| `code` | string 或 null | 模型服务返回的错误代码，可能省略。 |

:::
::::

:::::
::::::
:::::::