# 创建会话

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

创建本地会话，保存会话元数据及可选的条目摘要。

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

## 调用前准备

准备具有 Genesis 权限的[个人访问令牌](../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)。

## 请求体

将 `$GENESIS_ACCESS_TOKEN` 替换为个人访问令牌。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
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"
    }
  ]
}'
```

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

本地条目保存类型、角色和状态等摘要；消息正文需由应用自行保存。

::::{div} mo-api-parameter-table

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

::::

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

## 成功响应

成功时返回新会话及其元数据。

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

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

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 会话标识，用于查询、更新和删除会话。 |
| `object` | string | 固定为 `conversation`。 |
| `metadata` | object | 自定义会话元数据。 |
| `metadata.<key>` | any | 由调用方定义的键和值，例如 `purpose`。 |
| `status` | string | 会话状态，创建后为 `active`。 |
| `created_at` | integer | 创建时间，Unix 秒级时间戳。 |
| `updated_at` | integer | 最后更新时间，Unix 秒级时间戳。 |

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

## 错误响应

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

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

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

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

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

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

## 后续操作

保存响应中的 `id`，用于[查询会话](get-conversation.md)或[添加会话条目](create-item.md)。