OpenJellyfish
用户指南 · 08

Consumer 使用（外部 API 集成）

8.1 概述

Consumer 层面向外部用户和系统，通过 Service API Key 认证访问 AI Agent 能力。Base URL 与 Key 由部署方提供，勿使用文档中的示例域名或密钥。

完整接入说明见 CONSUMER_API_INTEGRATION.md（含环境变量 JF_BASE_URL / JF_API_KEY 示例）。

8.2 认证方式

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

text
Authorization: Bearer sk-svc-<由部署方提供>

8.3 API 接口

将 https://<你的部署域名> 替换为部署方给你的实例地址。

8.3.1 创建对话

bash
curl -X POST "https://<你的部署域名>/api/v1/conversations" \
  -H "Authorization: Bearer sk-svc-<由部署方提供>" \
  -H "Content-Type: application/json" \
  -d '{"title": "新对话"}'

8.3.2 发送消息（自定义 SSE）

bash
curl -X POST "https://<你的部署域名>/api/v1/chat" \
  -H "Authorization: Bearer sk-svc-<由部署方提供>" \
  -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 "https://<你的部署域名>/api/v1/chat/completions" \
  -H "Authorization: Bearer sk-svc-<由部署方提供>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

完全兼容 OpenAI API 格式，可直接替换 base_url 在已有的 OpenAI SDK 代码中使用。响应 usage 字段可能为 0；真实 Token 统计见 Admin 设置 → 用量统计。

8.3.4 媒体 Token（生成文件访问）

bash
curl "https://<你的部署域名>/api/v1/conversations/{conv_id}/media-token" \
  -H "Authorization: Bearer sk-svc-<由部署方提供>"

返回短期 token，供 <img src> / 下载链接使用（?token= 查询参数，无需 Authorization 头）。

8.3.5 多模态消息

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.6 获取对话历史

bash
curl "https://<你的部署域名>/api/v1/conversations/conv-id" \
  -H "Authorization: Bearer sk-svc-<由部署方提供>"

8.3.7 列出生成文件

bash
curl "https://<你的部署域名>/api/v1/conversations/conv-id/files" \
  -H "Authorization: Bearer sk-svc-<由部署方提供>"

# 下载（query 参数携带 token 或 key，支持 <img src>）
GET /api/v1/conversations/conv-id/files/images/xxx.png?token=<media-token>

8.3.8 上传附件

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

8.4 独立聊天页

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

text
https://<你的部署域名>/s/{service_id}
https://<你的部署域名>/s/{service_id}?key=sk-svc-<由部署方提供>   # 一键访问（等同分享 Key）

页面是 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 记忆系统→