# 创建 Chat Completion

向支持 Chat Completions 的 Genesis 模型发送一组消息，并从响应的 `choices[]` 读取生成结果。本页说明非流式调用；需要增量输出时，请使用[流式响应](streaming-responses.md)。

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

## 调用前准备

请求地址为 `https://token.moi.matrixorigin.cn/v1/chat/completions`。准备具有 Genesis 权限的访问凭据，以及从[查询模型列表](models.md)取得的模型 ID。

下方示例使用：

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

## 请求头

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

## 请求体

请求体包含以下字段。

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

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 支持 Chat Completions 的模型 ID。 |
| `messages` | array | 是 | 按顺序提交的消息列表。 |
| `messages[].role` | string | 是 | 消息角色。示例使用 `user`。 |
| `messages[].content` | string | 是 | 文本消息内容。 |
| `max_tokens` | integer | 否 | 本次生成的输出 Token 上限。仅使用所选模型支持的值。 |
| `temperature` | number | 否 | 采样温度。仅在模型支持时设置。 |

不要在非流式请求中设置 `stream: true`。模型、输入能力和可选参数以当前模型的实际支持范围为准。

## 请求示例

```bash
curl -X POST "https://token.moi.matrixorigin.cn/v1/chat/completions" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [
      {
        "role": "user",
        "content": "用一句话说明数据库事务的作用。"
      }
    ],
    "max_tokens": 128
  }'
```

## 成功响应

成功响应中的文本位于 `choices[].message.content`：

```json
{
  "id": "<COMPLETION_ID>",
  "object": "chat.completion",
  "model": "<MODEL_ID>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "事务将一组操作作为整体执行，以保证数据一致性。"
      },
      "finish_reason": "stop"
    }
  ]
}
```

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

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 本次 Completion 的标识。 |
| `object` | string | 响应对象类型，示例为 `chat.completion`。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `choices` | array | 生成结果列表。 |
| `choices[].index` | integer | 当前生成结果在 `choices` 中的下标。 |
| `choices[].message.role` | string | 消息角色。 |
| `choices[].message.content` | string | 助手生成的文本内容。 |
| `choices[].finish_reason` | string | 当前生成结束原因。只使用响应实际返回的值。 |

## 错误响应

接口不使用 `code`、`msg`、`data` 包络。收到非成功 HTTP 状态时，不要从 `choices[]` 读取结果。错误对象由兼容的模型服务返回；除 `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`
  - —
  - 请求体结构、消息内容或参数组合不符合接口要求。
  - 将请求缩减为 `model` 和一条文本消息后重新验证。
* - `401`
  - —
  - 凭据无效，或没有目标模型权限。
  - 检查认证 Header 和模型可见范围。
* - `403`
  - —
  - 凭据无效，或没有目标模型权限。
  - 检查认证 Header 和模型可见范围。
* - `429`
  - —
  - 当前请求受到速率、并发或额度限制。
  - 降低请求频率后再提交请求。
* - `5xx`
  - —
  - 服务或依赖暂时无法处理请求。
  - 稍后再次提交请求。
```

## 后续操作

- [流式响应](streaming-responses.md)
- [查询模型列表](models.md)
- [Responses](responses.md)