创建 Chat Completion¶

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

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

调用前准备¶

请求地址为 https://token.moi.matrixorigin.cn/v1/chat/completions。准备具有 Genesis 权限的访问凭据，以及从查询模型列表取得的模型 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。模型、输入能力和可选参数以当前模型的实际支持范围为准。

请求示例¶

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：

{
  "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 外的字段可能省略。

错误对象字段¶

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

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

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

常见 HTTP 错误¶

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

HTTP 状态码	错误代码	常见原因	建议操作
`400`	—	请求体结构、消息内容或参数组合不符合接口要求。	将请求缩减为 `model` 和一条文本消息后重新验证。
`401`	—	凭据无效，或没有目标模型权限。	检查认证 Header 和模型可见范围。
`403`	—	凭据无效，或没有目标模型权限。	检查认证 Header 和模型可见范围。
`429`	—	当前请求受到速率、并发或额度限制。	降低请求频率后再提交请求。
`5xx`	—	服务或依赖暂时无法处理请求。	稍后再次提交请求。

后续操作¶

最后更新于 2026 年 8 月 22 日