Skip to main content
Chapter navigation
User Guide · 08

Consumer Usage (External API Integration)

8.1 Overview

The Consumer layer serves external users and systems via Service API Key authentication. Base URL and keys are provided by your deployer — do not use example domains or keys from this doc.

Full integration guide: CONSUMER_API_INTEGRATION.md (examples use JF_BASE_URL / JF_API_KEY env vars).

8.2 Authentication

All Consumer API requests require:

text
Authorization: Bearer sk-svc-<provided-by-deployer>

8.3 API Endpoints

Replace https://<your-deployment-domain> with your instance URL.

8.3.1 Create Conversation

bash
curl -X POST "https://<your-deployment-domain>/api/v1/conversations" \
  -H "Authorization: Bearer sk-svc-<provided-by-deployer>" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Conversation"}'

8.3.2 Send Message (Custom SSE)

bash
curl -X POST "https://<your-deployment-domain>/api/v1/chat" \
  -H "Authorization: Bearer sk-svc-<provided-by-deployer>" \
  -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 "https://<your-deployment-domain>/api/v1/chat/completions" \
  -H "Authorization: Bearer sk-svc-<provided-by-deployer>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Fully compatible with OpenAI API format. Response usage may be zeros; real token stats are in Admin Settings → Usage.

8.3.4 Media Token (generated file access)

bash
curl "https://<your-deployment-domain>/api/v1/conversations/{conv_id}/media-token" \
  -H "Authorization: Bearer sk-svc-<provided-by-deployer>"

Returns a short-lived token for <img src> / download URLs (?token= query param).

8.3.5 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.6 Get Conversation History

bash
curl "https://<your-deployment-domain>/api/v1/conversations/conv-id" \
  -H "Authorization: Bearer sk-svc-<provided-by-deployer>"

8.3.7 List Generated Files

bash
curl "https://<your-deployment-domain>/api/v1/conversations/conv-id/files" \
  -H "Authorization: Bearer sk-svc-<provided-by-deployer>"

# Download (token or key in query for <img src>)
GET /api/v1/conversations/conv-id/files/images/xxx.png?token=<media-token>

8.3.8 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
https://<your-deployment-domain>/s/{service_id}
https://<your-deployment-domain>/s/{service_id}?key=sk-svc-<provided-by-deployer>   # One-click (equals sharing the key)

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.

Service Key billing: hosted / BYOK

Billing is selected per API Key, so one Service can issue both operator-paid (hosted) and caller-paid (byok) keys. Existing keys default to hosted. Use GET /api/v1/models with the Service key to inspect its billing mode and permitted models/hosts. BYOK chat requests supply provider, api_key, and model, plus base_url / region when needed; provider, model and endpoint must pass validation. Hosted keys reject caller credential fields and keep the Service's configured model behavior. The hosted / BYOK behavior above applies to DeepAgents Services. Codex / Cursor plan-backed Services use shared connections authorized by the host operator, with a fixed connection and model; they accept hosted plan keys only and reject BYOK and caller credentials.

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