Chat API

Chat API

Themis 提供 REST API，允许外部应用程序发送消息并接收 AI 响应。API 复用与 Web 和消息渠道相同的代理管线，因此空间中可用的所有技能、工具和 MCP 服务器都会自动生效。

认证

每个请求需要以 Bearer 令牌形式发送空间级 API 密钥:

Authorization: Bearer thm_0c53ab18dad0f404...

管理 API 密钥

进入 空间设置 > API
点击 Generate API Key
复制密钥（点击眼睛图标显示，Copy 按钮复制到剪贴板）
Regenerate 轮换密钥，Revoke 撤销密钥

API 密钥在存储时加密，作用域为单个空间。

端点

发送消息

POST /api/v1/conversations
Content-Type: application/json
Authorization: Bearer <api_key>

请求体:

字段	类型	必填	说明
`message`	string	是	消息文本
`conversation_id`	integer	否	继续已有对话
`callback`	boolean	否	完成时启用 Webhook 回调（需在空间设置中配置 Webhook URL）
`metadata`	object	否	存储在对话上的任意元数据

示例 – 新建对话:

curl -X POST https://your-themis.example.com/api/v1/conversations \
  -H "Authorization: Bearer thm_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "评估涩谷区神宫前1-1-1的房产"}'

示例 – 继续对话:

curl -X POST https://your-themis.example.com/api/v1/conversations \
  -H "Authorization: Bearer thm_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "收益预测如何？", "conversation_id": 325}'

响应 (201 Created):

{
  "id": 325,
  "status": "processing",
  "created_at": "2026-03-28T03:12:16Z",
  "updated_at": "2026-03-28T03:12:16Z",
  "messages": [
    {
      "id": 1851,
      "role": "user",
      "content": "评估涩谷区神宫前1-1-1的房产",
      "created_at": "2026-03-28T03:12:16Z"
    },
    {
      "id": 1852,
      "role": "assistant",
      "content": null,
      "created_at": "2026-03-28T03:12:16Z",
      "processing": true
    }
  ]
}

轮询响应

GET /api/v1/conversations/:id
Authorization: Bearer <api_key>

轮询此端点直到 status 从 "processing" 变为 "completed"。

响应字段:

字段	类型	说明
`id`	integer	对话 ID
`status`	string	`"processing"`, `"completed"`, `"input_requested"`
`messages`	array	按时间顺序排列的所有消息
`messages[].content`	string	消息文本（处理中为 `null`）
`messages[].images`	array	附加图片（如有）
`messages[].files`	array	附加文件（`filename`, `content_type`, `byte_size`, `url`）
`messages[].artifacts`	array	生成的构件（HTML 组件、图表等）

示例:

curl https://your-themis.example.com/api/v1/conversations/325 \
  -H "Authorization: Bearer thm_..."

流式发送消息

创建对话并以 SSE 流的形式在单个请求中接收响应。需在 空间设置 > API > SSE Streaming 中按空间启用。

POST /api/v1/conversations/stream
Content-Type: application/json
Authorization: Bearer <api_key>

请求体与 POST /api/v1/conversations 相同。返回 text/event-stream 而非 JSON。

示例:

curl -N -X POST https://your-themis.example.com/api/v1/conversations/stream \
  -H "Authorization: Bearer thm_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "评估涩谷区神宫前1-1-1的房产"}'

重连流

如果 SSE 连接断开，可重连到已有对话的流。传入 last_event_id 从断开处继续。

GET /api/v1/conversations/:id/stream?last_event_id=42
Authorization: Bearer <api_key>
Accept: text/event-stream

事件类型:

事件	说明	数据
`message_start`	开始处理	`conversation_id`, `message_id`
`status`	状态更新	`summary`
`thinking`	代理推理	`summary`
`tool_use`	工具调用	`tool`（工具名）
`tool_result`	工具结果	`tool_use_id`, `summary`, `is_error`
`content_delta`	文本片段	`delta`（500ms 节流）
`ping`	心跳（每15秒）	`{}`
`message_complete`	响应完成	`message_id`, `content`
`error`	处理失败	`message`
`done`	流结束	`{}`

示例流:

event: message_start
data: {"conversation_id":325,"message_id":1852}

event: thinking
data: {"summary":"正在分析房产位置并搜索可比物件..."}

event: tool_use
data: {"tool":"mcp__metabase__execute_query"}

event: tool_result
data: {"summary":"在涩谷区找到12个可比物件","is_error":false}

event: content_delta
data: {"delta":"根据分析，该房产"}

event: ping
data: {}

event: message_complete
data: {"message_id":1852,"content":"根据分析，该房产得分82/100..."}

event: done
data: {}

注意事项:

流超时为 3 分钟。长时间任务请重连后用轮询获取最终结果。
每个流占用一个 Web 服务器线程。批量任务请使用轮询。
内容增量以 500ms/20 字符最小值进行节流。

Webhook 回调

对于长时间运行的任务，在 POST 请求体中传入 "callback": true。当代理完成（或失败）时，Themis 会将结果 POST 到 空间设置 > API 中配置的 Webhook URL。

设置: 在空间设置 > API 中输入 Webhook URL（仅支持 HTTPS）。

请求:

curl -X POST https://your-themis.example.com/api/v1/conversations \
  -H "Authorization: Bearer thm_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "评估这个房产", "callback": true}'

回调载荷（POST 到您的 Webhook URL）:

{
  "id": 325,
  "status": "completed",
  "created_at": "2026-03-28T03:12:16Z",
  "updated_at": "2026-03-28T03:15:42Z",
  "messages": [
    { "id": 1851, "role": "user", "content": "评估这个房产" },
    { "id": 1852, "role": "assistant", "content": "根据分析..." }
  ]
}

验证: 每个回调包含 X-Themis-Signature 头（使用空间 API 密钥作为密钥的 HMAC-SHA256 签名）:

import hmac, hashlib

expected = hmac.new(api_key.encode(), body, hashlib.sha256).hexdigest()
assert signature == f"sha256={expected}"

注意事项:

Webhook URL 必须为 HTTPS。
网络错误时重试 3 次（30 秒间隔）。
completed 和 failed 状态均会触发回调。
默认禁用。仅当请求中包含 "callback": true 时才触发。

错误响应

状态码	响应体	原因
400	`{"error": "param is missing..."}`	缺少必填字段
401	`{"error": "Unauthorized"}`	API 密钥缺失或无效
404	`{"error": "Not found"}`	对话不存在
422	`{"error": "..."}`	校验失败

典型集成流程

1. POST /api/v1/conversations  { message: "..." }
   → 201  { id: 325, status: "processing" }

2. 轮询 GET /api/v1/conversations/325
   → 200  { status: "processing", messages: [...] }

3. 再次轮询...
   → 200  { status: "completed", messages: [..., { role: "assistant", content: "..." }] }

4. (可选) 用 conversation_id 继续对话
   POST /api/v1/conversations  { message: "追问", conversation_id: 325 }

需要实时反馈时使用流式端点:

1. POST /api/v1/conversations/stream  { message: "..." }
   → text/event-stream 实时接收事件

长时间任务（如房产评估）使用 Webhook 回调:

1. POST /api/v1/conversations  { message: "...", callback: true }
   → 201  { id: 325, status: "processing" }

2. 等待 Webhook URL 收到回调 POST
   → { id: 325, status: "completed", messages: [...] }