create_session-创建会话--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

请输入

会话 (Sessions)

create_session-创建会话

概述

/api/v1/sessions 接口用于创建一条新的会话记录。会话是 OpenViking 中承载消息、归档、记忆提取和上下文组装的基础单元。
你可以让系统自动生成 session_id，也可以显式指定一个业务侧自定义会话 ID，便于后续与外部会话系统进行映射。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口创建会话。建议同时明确当前请求所属的 agent_id，用于隔离不同 Agent 的会话上下文。

请求接口

URI

/api/v1/sessions
统一资源标识符。

请求方法

POST
客户端对服务器请求的操作类型。

请求头

参数	值	说明
Content-Type	`application/json`	请求消息类型
Authorization	`Bearer {api_key}`	鉴权
X-OpenViking-Agent	`{agent_id}`	Agent ID

请求参数

参数	类型	必选	默认值	备注
session_id	string	否	自动生成	会话 ID。若不传，系统自动生成；若传入，则创建指定 ID 的新会话。

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的数据对象
result.session_id	会话 ID
result.user	当前会话所属身份信息
result.user.account_id	工作区 ID
result.user.user_id	用户 ID
result.user.agent_id	Agent ID
error	失败时返回的错误对象
error.code	错误码字符串，常见值见下表
error.message	可读的错误描述

常见错误码

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
INVALID_ARGUMENT	请求体格式非法或 `session_id` 不符合约束

完整示例

示例一：自动生成会话 ID

curl -X POST `https://xxx/api/v1/sessions` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{}'

执行成功返回：

{
  "status": "ok",
  "result": {
    "session_id": "a1b2c3d4",
    "user": {
      "account_id": "default",
      "user_id": "alice",
      "agent_id": "default"
    }
  }
}

示例二：创建指定 ID 的会话

curl -X POST `https://xxx/api/v1/sessions` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "my-custom-session-id"
  }'

最近更新时间：2026.05.26 11:19:27

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

URI #

请求方法 #

请求头 #

请求参数 #

响应消息 #

常见错误码 #

完整示例 #

示例一：自动生成会话 ID #

示例二：创建指定 ID 的会话 #

概述