# Chat Completions

向支持 Chat Completions 的 Genesis 模型发送消息，并返回生成内容。

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

## 调用前准备

准备具有 Genesis 权限的访问凭据，并从[查看模型列表](../models.md)取得模型 ID。确认所选模型支持 Chat Completions。

## 请求体

将 `$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/chat/completions" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [
      {
        "role": "user",
        "content": "用一句话说明数据库事务的作用。"
      }
    ],
    "max_tokens": 128
  }'
```

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

::::{tab-set}
:::{tab-item} 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 要调用的 Chat Completions 模型 ID。 |
| `messages` | array of object | 是 | 按顺序提交的消息列表。 |
| `max_tokens` | integer | 否 | 本次生成的输出 Token 上限，仅使用所选模型支持的值。 |
| `temperature` | number | 否 | 采样温度，仅在所选模型支持时设置。 |
| `stream` | boolean | 否 | 设为 `true` 以请求流式输出，响应格式见「流式响应」。 |

:::
:::{tab-item} 消息项

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `role` | string | 是 | 消息角色。 |
| `content` | string | 是 | 消息的文本内容。 |

:::
::::

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

## 成功响应

服务返回模型生成的消息。

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

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

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

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 本次 Completion 的标识。 |
| `object` | string | 响应对象类型，示例为 `chat.completion`。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `choices` | array of object | 生成结果列表。 |

:::
:::{tab-item} 结果项

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `index` | integer | 当前生成结果在列表中的位置。 |
| `message` | object | 助手消息。 |
| `finish_reason` | string | 当前生成的结束原因。 |

:::
:::{tab-item} 消息对象

下面表格展开示例中 `choices[].message` 对象；每一行是该对象的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `role` | string | 消息角色。 |
| `content` | string | 助手生成的文本内容。 |

:::
::::

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

## 流式响应

将 `stream` 设为 `true` 并带 `Accept: text/event-stream` 请求头来请求流式输出。服务返回 `text/event-stream`；收到 `data: [DONE]` 前，持续读取事件中的增量内容。建立流前发生错误时，响应为 JSON 错误对象，结构同「错误响应」。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 调用示例

```bash
curl -N -X POST \
  "https://token.moi.matrixorigin.cn/v1/chat/completions" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [
      {
        "role": "user",
        "content": "用一句话说明主键的作用。"
      }
    ],
    "stream": true
  }'
```

:::::
:::::{tab-item} 响应示例

```text
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"主键"}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"用于唯一标识表中的每一行。"}}]}

data: [DONE]
```

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

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 事件对象类型，示例为 `chat.completion.chunk`。 |
| `choices` | array of object | 当前事件的增量列表。 |
| `[DONE]` | event marker | 正常结束标记；收到该标记后再将结果标记为完成。 |

:::
:::{tab-item} 结果项

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `delta` | object | 增量对象。 |

:::
:::{tab-item} 增量内容

下面表格展开示例中 `choices[].delta` 对象；每一行是该对象的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `content` | string | 存在时追加到当前文本。 |

:::
::::

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

## 错误响应

:::::::{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 | 模型服务返回的错误代码，可能省略。 |

:::
::::

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

## 后续操作

流式读取见上文「流式响应」。其他请求形态见 [Responses](responses.md) 和 [Messages（Anthropic）](anthropic-messages.md)。