创建会话

创建本地会话，保存自定义信息和可选的条目摘要。

POST https://token.moi.matrixorigin.cn/v1/conversations

调用前准备

准备具有 Genesis 权限的个人访问令牌。

认证方式见 Genesis 凭据规则。

请求体

将示例中的 $GENESIS_ACCESS_TOKEN 替换为实际值。

输入示例

curl -X POST "https://token.moi.matrixorigin.cn/v1/conversations" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "purpose": "support"
  },
  "items": [
    {
      "type": "message",
      "role": "user"
    }
  ]
}'

参数说明

参数	类型	是否必填	说明
metadata	object	否	会话的自定义信息。
metadata.<key>	any	否	自定义键和值，例如 purpose。
items	array of object	否	创建会话时一并添加的条目摘要。
items[].type	string	否	条目类型，例如 message。
items[].role	string	否	条目角色，例如 user。
items[].status	string	否	条目状态，省略时为 active。

请求体必须为 JSON 对象。metadata 用于保存自定义键值对。服务先创建会话记录，再保存初始条目摘要。

成功响应

响应示例

{
  "id": "$CONVERSATION_ID",
  "object": "conversation",
  "metadata": {
    "purpose": "support"
  },
  "status": "active",
  "created_at": 1780000000,
  "updated_at": 1780000000
}

字段说明

字段	类型	说明
id	string	会话标识，用于查询、更新和删除会话。
object	string	固定为 conversation。
metadata	object	会话的自定义信息。已保存的值不是 JSON 对象时，返回 {}。
metadata.<key>	any	自定义键和值，例如 purpose。
status	string	会话状态，创建后为 active。
created_at	integer	创建时间，Unix 秒级时间戳。
updated_at	integer	最后更新时间，Unix 秒级时间戳。

错误响应

请求体不是 JSON 对象时返回 HTTP 400。将请求体改为对象后重新提交。

响应示例

{
  "error": {
    "message": "request body must be a JSON object",
    "type": "invalid_request",
    "code": "invalid_request"
  }
}

字段说明

字段	类型	说明
error	object	错误信息。
error.message	string	错误原因。
error.type	string	错误类别。
error.code	string	错误代码。

最后更新于 2026 年 10 月 19 日