对话 API
对话 API 是 Build AI Template 的核心，负责处理所有与 AI 聊天相关的功能。包括创建对话、发送消息、获取历史记录以及管理可用的 AI Agent。
API 端点详情
获取可用 Agent 列表
GET /chat/agents/active
获取所有当前可用的 AI Agent 列表，供用户在创建新对话时选择。
响应 (200 OK):
[
{
"id": 1,
"name": "GPT-4.1 Mini",
"description": "OpenAI 最新、最快的模型",
"avatar": "/avatars/gpt-4.1-mini.png",
// ... 其他 agent 信息
}
]创建新对话
POST /chat
创建一个新的对话会话，并将其与一个 Agent 关联。
请求体:
{
"title": "我的新对话",
"agent_id": 1,
"lang": "zh"
}响应 (201 Created):
{
"id": 123,
"title": "我的新对话",
"user_id": 1,
"agent_id": 1,
"created_at": "...",
"updated_at": "...",
"agent": {
// ... 关联的 agent 信息
}
}发送消息
POST /chat/message
在指定对话中发送一条消息并获取 AI 回复。支持流式 (stream=true) 和非流式响应。
请求体:
{
"chat_id": 123,
"content": "你好，世界！",
"role": "user", // 只能是 'user'
"lang": "zh"
}Query 参数:
stream(boolean, optional): 设置为true以启用流式响应。默认为false。
💡 响应说明
- 非流式: 返回一个包含用户消息和 AI 回复消息对象的数组。
- 流式: 返回一个
text/plain类型的流。前端需要逐步接收和渲染文本块。流结束后，会包含一个特殊标记__TOKEN_USAGE__来传递 Token 使用信息。
响应 (200 OK - 非流式):
[
{ // 用户消息
"id": 1, "chat_id": 123, "content": "你好，世界！", "role": "user", ...
},
{ // AI 回复
"id": 2, "chat_id": 123, "content": "你好！有什么可以帮助你的吗？", "role": "assistant", "token_usage": { ... }, ...
}
]获取对话列表
GET /chat
获取当前用户的所有对话列表，支持分页。
Query 参数:
limit(integer, optional): 每页数量，默认 20，最大 100。offset(integer, optional): 偏移量，默认 0。include_messages(boolean, optional): 是否在返回的对话中包含所有消息，默认false。
响应 (200 OK):
[
{
"id": 123,
"title": "我的新对话",
// ... 其他对话信息
},
// ... 更多对话
]获取指定对话详情
GET /chat/{chat_id}
获取单个对话的详细信息，包括其所有历史消息。
响应 (200 OK):
{
"id": 123,
"title": "我的新对话",
"messages": [
{ "role": "user", "content": "你好" },
{ "role": "assistant", "content": "你好！" }
],
"agent": {
// ... 关联的 agent 信息
}
}更新对话
PUT /chat/{chat_id}
更新对话的属性，例如修改标题。
请求体:
{
"title": "更新后的对话标题"
}删除对话
DELETE /chat/{chat_id}
软删除一个对话。数据仍在数据库中，但对用户不可见。
响应 (200 OK):
{
"message": "对话已删除"
}