星悟引擎 API 接口文档 v1.0
项目名称：星悟引擎（XingWu AI Engine）
API 版本：v1.0
基础 URL：/ai
API 概述
该文档描述星悟引擎的核心对话接口。前端可据此与引擎交互，发送用户消息并获取回复。支持流式 (streaming) 与阻塞 (blocking) 两种模式。
认证
所有接口通过 apiKey 鉴权，示例：e7fc7a1938df3f34d05487ceef3a908d
接口列表
1. 对话服务接口 POST /chatMessages
核心接口，支持问答体系、知识库检索、加密货币分析、新闻聚合及 Agent 对话。
请求参数
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|---|---|---|---|---|
| apiKey | String | 是 | 鉴权 Key | e7fc... |
| query | String | 是 | 用户输入 | "BTC 价格" |
| isStream | Boolean | 否 | 是否流式输出，默认 true | true |
| conversationId | String | 否 | 续接会话 ID | 6c1a58... |
响应示例 A：阻塞模式 (isStream =false)
{
"result":{"returnCode":"0","returnMessage":"成功","returnUserMessage":"目前比特币价格是 $98,000"}
}
响应示例 B：流式模式 (isStream =true)
Content‑Type：text/event-stream
data: {"task_id":"70380236-2f5b-40a4-b75b-b93f74077984"}
data: {"conversation_id":"6c1a58d2-7b81-46ce-8248-b609f742659f"}
data: {"content":"你"}
data: {"content":"好"}
data: [DONE]
前端处理建议：
1️⃣ 首包 task_id 需保存；
2️⃣ 收到 [DONE] 后关闭 SSE 连接。
1️⃣ 首包 task_id 需保存；
2️⃣ 收到 [DONE] 后关闭 SSE 连接。
2. 任务中断接口 POST /stop
立即中断正在生成的流式响应，释放资源。
参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| apiKey | String | 是 | 鉴权 Key |
| conversationId | String | 否 | 当前会话 ID |
| taskId | String | 是 | /chatMessages 首包 task_id |
响应示例
{
"data":"已停止思考",
"result":{"returnCode":"0","returnMessage":"成功"}
}
3. 业务代码表 (returnCode)
| 代码 | 描述 | 说明 |
|---|---|---|
| 0 | 成功 | 请求正常 |
| 1 | 失败 | 业务执行失败 |
| 10000 | 参数错误 | 缺少必要参数 |
| 11110 | 被限流 | 提问频率过高 |
| 10001 | 数据不存在 | 请求数据不存在 |
| 10002 | 数据已存在 | 不能重复添加 |