创建 Chat Completion¶

提交对话消息，取得模型生成的回复。

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

调用前准备¶

准备用于 Genesis 调用的个人访问令牌或服务账号 API Key。创建和权限配置参阅管理 Genesis 访问凭据。
调用查询可调用模型，使用 type=chat 缩小模型范围。模型列表当前不提供 Chat Completions 专用能力标签；如果调用返回 endpoint_capability_mismatch，请选择其他 chat 模型。

请求体¶

将示例中的 $GENESIS_ACCESS_TOKEN 和 $MODEL_ID 分别替换为访问凭据和所选模型的 ID。

输入示例

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": "Reply with OK."
    }
  ],
  "max_tokens": 64
}'

参数说明

下表列出文本对话字段。图像输入和工具调用所需的字段未在此展开。

参数	类型	是否必填	说明
`model`	string	是	所选模型的 ID，取自模型查询结果中的 `data[].id`。
`messages`	array of object	是	按对话顺序排列的非空消息列表。
`messages[].role`	string	是	文本对话使用 `system`、`user` 或 `assistant`。
`messages[].content`	string 或 array of object	否	文本内容或文本块列表。
`messages[].content[].type`	string	文本块中必填	文本块填写 `text`。
`messages[].content[].text`	string	文本块中必填	非空文本内容。
`max_tokens`	integer	否	输出 Token 上限；推理模型的预算还可能包含推理 Token。按模型支持的范围设置。
`temperature`	number	否	采样温度，仅在模型支持时设置。
`top_p`	number	否	核采样参数，仅在模型支持时设置。
`stream`	boolean	否	设为 `true` 返回流式增量。

成功响应¶

响应示例

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 1,
    "total_tokens": 13
  }
}

字段说明

字段	类型	说明
`id`	string	本次生成的标识。
`object`	string	对象类型 `chat.completion`。
`model`	string	处理请求的模型。
`choices`	array of object	生成结果。
`choices[].index`	integer	结果序号，从 0 开始。
`choices[].message`	object	生成的助手消息。
`choices[].message.role`	string	消息角色 `assistant`。
`choices[].message.content`	string 或 null	生成文本；某些非文本结果中可能为空。
`choices[].finish_reason`	string 或 null	结束原因；`stop` 表示正常停止，`length` 表示达到长度限制。
`usage`	object	模型返回的 Token 用量。
`usage.prompt_tokens`	integer	输入 Token 数。
`usage.completion_tokens`	integer	生成 Token 数。
`usage.total_tokens`	integer	输入与生成 Token 总数。

流式响应¶

在请求体中将 stream 设为 true，逐段接收模型生成的内容。服务通过服务器发送事件（SSE）返回增量结果，发送 data: [DONE] 后结束响应。

输入示例

curl -N -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": "Reply with OK."
    }
  ],
  "max_tokens": 64,
  "stream": true
}'

响应示例

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"OK"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

字段说明

字段	类型	说明
`choices[].index`	integer	生成结果的序号，用于区分不同结果。
`choices[].delta.content`	string	本次返回的增量文本，按接收顺序追加到对应结果。
`choices[].finish_reason`	string 或 null	对应结果的生成结束原因；尚未结束时为 `null`。

按完整 SSE 事件解析响应；一次网络读取可能包含部分事件或多个事件，应先缓冲再解析。未收到 data: [DONE] 就断开连接时，已收到的内容可能不完整。

错误响应¶

缺少必填模型 ID 时返回 HTTP 400。补充模型 ID 后重新提交。

所选模型没有可用的 Chat Completions 路由时，返回 HTTP 503，且 error.code 和 error.type 为 endpoint_capability_mismatch。重新查询 type=chat 模型，并选择其他模型重试。

响应示例

{
  "error": {
    "message": "missing required parameter: model",
    "type": "invalid_request",
    "code": "invalid_request"
  }
}

字段说明

字段	类型	说明
`error`	object	错误信息。
`error.message`	string	错误原因；示例表示缺少模型 ID。
`error.type`	string	错误类别，例如 `invalid_request` 或 `endpoint_capability_mismatch`。模型服务返回时可能省略。
`error.code`	string 或 null	错误代码，例如 `invalid_request` 或 `endpoint_capability_mismatch`。模型服务返回时可能省略。

最后更新于 2026 年 9 月 11 日