创建会话

接口说明

选择智能体后，调用此接口在服务端创建一条会话记录，并返回 conversationId。

后续所有需要会话上下文的接口（流式聊天、灵感回复、图片生成）均需携带此 conversationId。

使用时机：用户选择/切换智能体时调用一次，整个对话周期内复用同一个 conversationId；切换至新智能体时重新调用本接口获取新的 conversationId。

基本信息

项目	说明
接口路径	POST /v1/chat/conversation
响应类型	application/json
认证方式	API Key + 请求签名（认证说明）

请求体

{
  "agentId": "agent-uuid"
}

字段	类型	必填	说明
agentId	string	✅	智能体 ID，从智能体列表接口 /v1/agent/list 获取

签名示例（仅 agentId 一个字段）：

待签名字符串 = "agentId=agent-uuid" + apiSecret
X-Signature = sha256(待签名字符串)

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "conversationId": "a1b2c3d4e5f6..."
  },
  "traceId": "9fU0kfWy3E8YFGjS5S8bLPlAXG8xhdTH",
  "timestamp": "1773298769366"
}

字段	类型	说明
data.conversationId	string	会话 ID（UUID 格式去除连字符），后续所有聊天相关接口均需传入此值

错误响应

HTTP 状态码	说明
401	认证失败
400	请求参数缺失或格式错误
500	服务端内部错误

业务错误（HTTP 200）：

message	说明
agentId is required	缺少 agentId 字段
Invalid API key	API Key 无效或已禁用
Too many requests, please try again later	触发频率限制
API key usage limit reached	达到总调用次数上限

客户端示例

async function createConversation(apiKey, apiSecret, userId, agentId) {
  const body = { agentId }
  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, body)

  const response = await fetch('/v1/chat/conversation', {
    method: 'POST',
    headers,
    body: JSON.stringify(body),
  })

  const result = await response.json()
  if (!result.success) throw new Error('创建会话失败：' + result.message)
  return result.data.conversationId
}

使用时序

Client                         Sonaops Open API              PostgreSQL
  │                                   │                           │
  │  [用户选择智能体]                   │                           │
  │                                   │                           │
  │  POST /v1/chat/conversation       │                           │
  │  { "agentId": "agent-uuid" }      │                           │
  │──────────────────────────────────>│                           │
  │                                   │  INSERT open_chat_conversation
  │                                   │──────────────────────────>│
  │                                   │<──────────────────────────│
  │  { "data": { "conversationId":    │                           │
  │    "a1b2c3d4..." } }              │                           │
  │<──────────────────────────────────│                           │

conversationId 生命周期

时机	操作
用户选择/切换智能体	调用本接口创建新会话，获得新 conversationId
同一智能体持续对话	复用同一 conversationId，无需重新创建
用户退出/页面刷新	conversationId 可持久化（localStorage 等），继续使用已有会话