add_message-添加消息--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

请输入

会话 (Sessions)

add_message-添加消息

概述

/api/v1/sessions/{id}/messages 接口用于向指定会话追加一条消息。
该接口支持两种写法：

使用 content 传入纯文本内容的简单模式
使用 parts 传入结构化消息内容的 Parts 模式

如果目标会话不存在，系统会在首次添加消息时自动创建会话。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口写入消息。

请求接口

URI

/api/v1/sessions/{id}/messages
统一资源标识符。

请求方法

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

请求头

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

请求参数

参数	类型	位置	必选	默认值	备注
id	string	Path	是	--	会话 ID
role	string	Body	是	--	消息角色，取值通常为 `user` 或 `assistant`
content	string	Body	条件必选	--	纯文本消息内容，和 `parts` 二选一
parts	array	Body	条件必选	--	结构化消息片段，和 `content` 二选一；若同时传入，`parts` 优先
created_at	string	Body	否	--	ISO 8601 时间戳

parts 中常见片段类型包括：

text：文本片段
context：上下文片段
tool：工具调用片段

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的数据对象
result.session_id	会话 ID
result.message_count	当前会话中的消息数量
error	失败时返回的错误对象
error.code	错误码字符串
error.message	可读的错误描述

常见错误码

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
INVALID_ARGUMENT	未提供 `content` 和 `parts`，或请求体格式错误

完整示例

示例一：简单模式写入文本消息

curl -X POST `https://xxx/api/v1/sessions/a1b2c3d4/messages` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "How do I authenticate users?"
  }'

示例二：Parts 模式写入结构化消息

curl -X POST `https://xxx/api/v1/sessions/a1b2c3d4/messages` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "assistant",
    "parts": [
      {"type": "text", "text": "Based on the authentication guide..."},
      {"type": "context", "uri": "viking://resources/docs/auth/", "context_type": "resource", "abstract": "Auth guide"}
    ]
  }'

执行成功返回：

{
  "status": "ok",
  "result": {
    "session_id": "a1b2c3d4",
    "message_count": 2
  }
}

示例三：批量添加多条消息

curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages/batch \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "How do I authenticate users?"},
      {"role": "assistant", "content": "You can use OAuth 2.0 for authentication."},
      {"role": "user", "content": "Any specific recommendations?"}
    ]
  }'

最近更新时间：2026.06.02 16:07:51

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

URI #

请求方法 #

请求头 #

请求参数 #

响应消息 #

常见错误码 #

完整示例 #

示例一：简单模式写入文本消息 #

示例二：Parts 模式写入结构化消息 #

示例三：批量添加多条消息 #

概述