JellyfishBot
用户指南 · 08

Consumer 使用（外部 API 集成）

8.1 概述

Consumer 层面向外部用户和系统，通过 Service API Key 认证访问 AI Agent 能力。

8.2 认证方式

所有 Consumer API 请求需在 HTTP Header 中携带：

text
Authorization: Bearer sk-svc-xxxxxxxxxxxxx

8.3 API 接口

8.3.1 创建对话

bash
curl -X POST http://your-host/api/v1/conversations \
  -H "Authorization: Bearer sk-svc-xxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "新对话"}'

8.3.2 发送消息（自定义 SSE）

bash
curl -X POST http://your-host/api/v1/chat \
  -H "Authorization: Bearer sk-svc-xxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"conversation_id": "conv-id", "message": "你好"}'

SSE 事件类型与 Admin 端一致：token / thinking / tool_call / tool_result / done / error 等（详见 开发指南 §5.5）。

8.3.3 OpenAI 兼容接口

bash
curl -X POST http://your-host/api/v1/chat/completions \
  -H "Authorization: Bearer sk-svc-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

完全兼容 OpenAI API 格式，可直接替换 base_url 在已有的 OpenAI SDK 代码中使用。

8.3.4 多模态消息

Consumer 支持发送图片 + 文字：

json
{
  "conversation_id": "conv-id",
  "message": [
    {"type": "text", "text": "这张图片是什么？"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
  ]
}

GPT-4o / Claude Sonnet/Opus 均原生支持。

8.3.5 获取对话历史

bash
curl http://your-host/api/v1/conversations/conv-id \
  -H "Authorization: Bearer sk-svc-xxx"

8.3.6 列出生成文件

bash
curl http://your-host/api/v1/conversations/conv-id/files \
  -H "Authorization: Bearer sk-svc-xxx"

# 下载某个文件（query 参数携带 key 以支持 <img src>）
GET /api/v1/conversations/conv-id/files/images/xxx.png?key=sk-svc-xxx

8.3.7 上传附件

bash
# 用户附件存储到 query_appendix/
GET /api/v1/conversations/conv-id/attachments/images/abc.jpg

8.4 独立聊天页

每个 Service 可通过以下 URL 访问独立的聊天网页：

text
http://your-host/s/{service_id}
http://your-host/s/{service_id}?key=sk-svc-xxx   # 一键访问

页面是 React 应用（Vite multi-entry），由 FastAPI 注入 Service 配置 + key 后渲染。Key 写入 localStorage 后会立即从 URL 中清除。

8.5 send_message 工具行为

如果你的 Service 启用了 humanchat capability：

  • Web 渠道（/api/v1/* 或 /s/{sid}）：不会注入 send_message 工具，因为 Agent 输出已直接流给浏览器
  • WeChat 渠道（Service 微信扫码）：注入 send_message，Agent 调用时由后端拦截并通过 iLink 投递到对应微信用户
  • Scheduler 渠道（定时任务）：同 WeChat

8.5.1 媒体自动发送（<<FILE:>> 标签）

Agent 在 send_message 的文本中输出 <<FILE:/generated/images/xxx.png>> 标签时，后端会自动：

  1. 从文本中抽取标签
  2. 把对应文件单独发送（图片/视频/语音/PDF）
  3. 把抽取后的纯文本作为消息发出

这是为了和聊天页 markdown 渲染统一约定。无需 Consumer 端做任何处理。

上一篇←Service 渠道：让 Consumer 通过微信扫码使用下一篇Soul 记忆系统→