Service API 接入 · 04
主要端点
3.1 POST /chat/completions —— OpenAI 兼容（推荐）
可以直接用 OpenAI 官方 SDK，把 base_url 改成部署方提供的地址即可。
请求体
jsonc
{
"messages": [
{"role": "user", "content": "..."}
],
"stream": true, // 默认 true；false 走非流式
"conversation_id": "conv-xxx" // 可选，续会话用；不传就新建
}流式响应（stream=true，与 OpenAI 完全一致）
Content-Type: text/event-stream，每条事件以 data: 开头，\n\n 结尾：
text
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1745300000,"model":"...","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1745300000,"model":"...","choices":[{"index":0,"delta":{"content":"深"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1745300000,"model":"...","choices":[{"index":0,"delta":{"content":"度"},"finish_reason":null}]}
...
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1745300000,"model":"...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]非流式响应（stream=false）
jsonc
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1745300000,
"model": "...",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "..."},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
"conversation_id": "conv-xxx" // ⚠️ 非标准扩展字段
}3.2 与 OpenAI 标准的关键差异（必读）
| 字段 | OpenAI | OpenJellyfish | 行为 |
|---|---|---|---|
messages | 完整历史 | 只取最后一条 role="user" | 历史由服务端按 conversation_id 维护，不依赖客户端传入 |
conversation_id | ❌ | ✅ 扩展字段 | 不传 → 新建会话；带上 → 续会话 |
model | 决定模型 | 被忽略 | 模型在 service 创建时绑定，客户端传啥都没用 |
temperature / top_p / max_tokens / stop / presence_penalty 等 | 影响生成 | 被忽略 | 同上，service 端写死 |
tools / tool_choice / function_call / response_format / logprobs / seed | 支持 | 不支持 | service 内部可能调用工具，但不暴露给消费者 |
usage 字段 | 真实 token 数 | 全为 0 | OpenAI 兼容端点当前未返回真实 token；管理端可在 设置 → 用量统计 查看 LLM 用量 |
多模态 image_url | 支持 | 不支持（请走 /chat） | 见 §3.3 |
总之：把
messages当成"只发送本轮用户消息"，把上下文交给conversation_id管。
3.3 POST /chat —— 自定义 SSE（多模态、富事件）
如果你想传图片输入，或想接收 thinking / tool / subagent 等过程事件用于精细 UI，请用这个端点。
请求体
jsonc
{
"conversation_id": "conv-xxx",
"message": "..." // 字符串 或 OpenAI 多模态 content blocks 数组
}多模态示例：
jsonc
{
"conversation_id": "conv-xxx",
"message": [
{"type": "text", "text": "这张图里有什么？"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AA..."}}
]
}响应
Content-Type: text/event-stream。注意：不是标准 SSE 的 event: <type> + data: <json> 双行格式，而是只发 data: 行，事件类型放在 JSON 体的 type 字段里：
text
data: {"type": "thinking", "content": "用户想让我..."}
data: {"type": "tool_call", "name": "web_search", "args": {"query": "..."}}
data: {"type": "tool_call_chunk", "args_delta": "..."}
data: {"type": "tool_result", "name": "web_search", "content": "..."}
data: {"type": "token", "content": "深"}
data: {"type": "token", "content": "度"}
data: {"type": "done"}type | 字段 | 说明 |
|---|---|---|
thinking | content | 模型 reasoning / chain-of-thought 增量（仅 thinking 模型有） |
tool_call | name, args | Agent 决定调用某工具 |
tool_call_chunk | args_delta | 工具参数流式增量（部分模型分块输出参数时） |
tool_result | name, content | 工具返回结果（截断到 500 字符） |
token | content | 最终回答 token 增量（拼起来就是完整答案） |
done | — | 正常结束 |
error | content | 流式过程中出错；之后不会再有 done |
没有
[DONE]终止符（那是 §3.1 OpenAI 兼容才有），自定义 SSE 用{"type": "done"}表示结束。如果只是做基础对话集成，用 §3.1 的 OpenAI 兼容端点就够了。
/chat留给需要还原"agent 思考过程"UI 的场景。
3.4 会话管理
| 路径 | 方法 | 用途 |
|---|---|---|
/conversations | POST | 显式创建会话（一般不需要，/chat/completions 会自动建） |
/conversations/{conv_id} | GET | 取整段会话历史 |
/conversations/{conv_id}/files | GET | 列出 Agent 在本次会话中生成的文件 |
/conversations/{conv_id}/files/{path} | GET | 下载生成文件（图片、文档等）；支持 ?token= 供 <img src> 鉴权 |
/conversations/{conv_id}/media-token | GET | 获取短期媒体访问 token（独立聊天页用） |
POST /conversations 请求 / 响应
jsonc
// 请求体（title 可选）
{ "title": "客户咨询 #123" }
// 响应
{
"id": "conv-xxxxxxxxxxxx",
"title": "客户咨询 #123",
"created_at": "2026-04-22T...",
"updated_at": "2026-04-22T..."
}GET /conversations/{conv_id} 响应
jsonc
{
"id": "conv-xxx",
"title": "...",
"created_at": "...",
"updated_at": "...",
"messages": [
{"role": "user", "content": "...", "created_at": "..."},
{"role": "assistant", "content": "...", "created_at": "..."}
// ...
]
}不存在 / 不属于当前 service Key 的
conv_id→404 {"detail": "Conversation not found"}。