JellyfishBot
User Guide · 08

Consumer Usage (External API Integration)

8.1 Overview

The Consumer layer serves external users and systems, accessing AI Agent capabilities authenticated with Service API Keys.

8.2 Authentication

All Consumer API requests require in the HTTP header:

text
Authorization: Bearer sk-svc-xxxxxxxxxxxxx

8.3 API Endpoints

8.3.1 Create Conversation

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

8.3.2 Send Message (Custom 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": "Hello"}'

SSE event types match Admin side: token / thinking / tool_call / tool_result / done / error, etc. (see Developer Guide §5.5).

8.3.3 OpenAI-Compatible Endpoint

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": "Hello"}],
    "stream": true
  }'

Fully compatible with OpenAI API format — directly replace base_url in existing OpenAI SDK code.

8.3.4 Multimodal Messages

Consumer supports sending images + text:

json
{
  "conversation_id": "conv-id",
  "message": [
    {"type": "text", "text": "What is in this image?"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
  ]
}

GPT-4o / Claude Sonnet/Opus support natively.

8.3.5 Get Conversation History

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

8.3.6 List Generated Files

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

# Download a file (query param carries key to support <img src>)
GET /api/v1/conversations/conv-id/files/images/xxx.png?key=sk-svc-xxx

8.3.7 User Attachments

bash
# User attachments stored in query_appendix/
GET /api/v1/conversations/conv-id/attachments/images/abc.jpg

8.4 Standalone Chat Page

Each Service has an accessible standalone chat web page:

text
http://your-host/s/{service_id}
http://your-host/s/{service_id}?key=sk-svc-xxx   # One-click access

The page is a React application (Vite multi-entry), FastAPI injects Service config + key before rendering. Key is written to localStorage then immediately cleared from URL.

8.5 send_message Tool Behavior

If your Service has humanchat capability enabled:

  • Web channel (/api/v1/* or /s/{sid}): does not inject send_message tool — Agent output already streams to browser
  • WeChat channel (Service WeChat QR): injects send_message — when Agent calls it, backend intercepts and delivers via iLink to the corresponding WeChat user
  • Scheduler channel (scheduled tasks): same as WeChat

8.5.1 Auto Media Sending (<<FILE:>> Tags)

When Agent outputs <<FILE:/generated/images/xxx.png>> tag in send_message text, backend automatically:

  1. Extracts tags from text
  2. Sends corresponding file separately (image/video/voice/PDF)
  3. Sends extracted plain text as the message

This matches the chat page markdown rendering convention. Consumer side needs no special handling.

Previous←Service Channel: Let Consumers Use via WeChat QRNextSoul Memory System→