[RFC] 126 - LobeChat OpenAPI #8679

MarioJames · 2025-08-05T10:02:15Z

MarioJames
Aug 5, 2025

LobeChat API 接口文档

概述

本文档整理了 LobeChat 项目中所有的 OpenAPI 接口，这些接口基于 Hono 框架构建，提供了完整的 AI 聊天应用功能。所有接口都位于 /api/v1/ 路径下。

认证说明

所有接口都需要用户认证（requireAuth 中间件），并且大多数接口还需要特定的 RBAC 权限。权限范围包括：

ALL: 全局权限
WORKSPACE: 工作空间权限
OWNER: 所有者权限

1. Agents 模块 (智能体管理)

1.1 获取系统中所有的 Agent 列表

功能: 获取系统中所有的 Agent 列表
请求方式: GET
请求路径: /api/v1/agents
权限要求: Agent 读取权限 (ALL, WORKSPACE)
备注: 需要 Agent 读取权限

1.2 创建智能体

功能: 创建新的智能体
请求方式: POST
请求路径: /api/v1/agents
权限要求: Agent 创建权限 (仅管理员)
参数: 创建 Agent 请求体 (CreateAgentRequestSchema)

1.3 更新智能体

功能: 更新智能体信息
请求方式: PUT
请求路径: /api/v1/agents/:id
权限要求: Agent 更新权限 (仅管理员)
参数: Agent ID (路径参数) + 更新请求体 (UpdateAgentRequestSchema)

1.4 删除智能体

功能: 删除智能体
请求方式: DELETE
请求路径: /api/v1/agents/:id
权限要求: Agent 删除权限 (仅管理员)
参数: Agent ID (路径参数)

1.5 根据 ID 获取 Agent 详情

功能: 根据 ID 获取 Agent 详情
请求方式: GET
请求路径: /api/v1/agents/:id
权限要求: Agent 读取权限 (ALL, WORKSPACE, OWNER)
参数: Agent ID (路径参数)

1.6 根据 Session ID 获取关联的 Agent 详情

功能: 根据 Session ID 获取关联的 Agent 详情
请求方式: GET
请求路径: /api/v1/agents/session/:sessionId
权限要求: Agent 读取权限 (ALL, WORKSPACE, OWNER)
参数: Session ID (路径参数)

2. Chat 模块 (聊天功能)

2.1 通用聊天接口

功能: 处理通用聊天请求
请求方式: POST
请求路径: /api/v1/chat
权限要求: 无特殊权限要求
参数: 聊天服务参数 (ChatServiceParamsSchema)

2.2 翻译接口

功能: 文本翻译服务
请求方式: POST
请求路径: /api/v1/chat/translate
权限要求: 无特殊权限要求
参数: 翻译服务参数 (TranslateServiceParamsSchema)

2.3 生成回复接口

功能: 生成 AI 回复
请求方式: POST
请求路径: /api/v1/chat/generate-reply
权限要求: 无特殊权限要求
参数: 消息生成参数 (MessageGenerationParamsSchema)

3. Files 模块 (文件管理)

3.1 获取文件列表

功能: 获取文件列表，支持分页、过滤和搜索
请求方式: GET
请求路径: /api/v1/files
权限要求: 需要用户认证
查询参数:
- page: 页码 (可选，默认1)
- pageSize: 每页数量 (可选，默认20，最大100)
- fileType: 文件类型过滤 (可选)
- knowledgeBaseId: 知识库ID过滤 (可选)
- search: 搜索关键词 (可选)

3.2 单文件上传

功能: 上传单个文件
请求方式: POST
请求路径: /api/v1/files/upload
权限要求: 需要用户认证
内容类型: multipart/form-data
表单字段:
- file: 要上传的文件 (必需)
- knowledgeBaseId: 知识库ID (可选)
- sessionId: 会话ID (可选)
- skipCheckFileType: 是否跳过文件类型检查 (可选)
- directory: 上传目录 (可选)

3.3 批量文件上传

功能: 批量上传多个文件
请求方式: POST
请求路径: /api/v1/files/batch-upload
权限要求: 需要用户认证
内容类型: multipart/form-data
表单字段:
- files: 要上传的文件列表 (必需)
- 其他字段同单文件上传

3.4 公共文件上传

功能: 上传公共文件，设置为永久可访问
请求方式: POST
请求路径: /api/v1/files/upload-public
权限要求: 需要用户认证
特点: 自动设置为公共读取权限，适用于头像等长期访问的文件

3.5 获取文件详情

功能: 根据文件ID获取文件详情
请求方式: GET
请求路径: /api/v1/files/:id
权限要求: 需要用户认证
参数: 文件ID (路径参数)

3.6 获取文件访问URL

功能: 获取文件的临时访问URL
请求方式: GET
请求路径: /api/v1/files/:id/url
权限要求: 需要用户认证
查询参数: expiresIn: URL过期时间（秒，范围60-7200，默认3600）

3.7 获取文件永久访问URL

功能: 获取文件的永久公共URL
请求方式: GET
请求路径: /api/v1/files/:id/permanent-url
权限要求: 需要用户认证
特点: 返回永久可访问的公共URL，需要文件设置了public-read ACL

3.8 解析文件内容

功能: 解析文档文件的文本内容
请求方式: POST
请求路径: /api/v1/files/:id/parse
权限要求: 需要用户认证
查询参数: skipExist: 是否跳过已存在的解析结果 (可选，默认false)

3.9 上传文件并解析文件内容

功能: 上传文件并自动解析内容
请求方式: POST
请求路径: /api/v1/files/upload-and-parse
权限要求: 需要用户认证
功能: 结合上传和解析功能，返回组合结果

3.10 批量获取文件详情和内容

功能: 根据文件ID列表批量获取文件详情
请求方式: POST
请求路径: /api/v1/files/batch-get-parsed-files
权限要求: 需要用户认证
请求体: { "fileIds": ["file1", "file2", "file3"] }
功能: 图片文件返回base64内容，非图片文件返回解析后的文本内容

3.11 删除文件

功能: 删除指定文件
请求方式: DELETE
请求路径: /api/v1/files/:id
权限要求: 需要用户认证
参数: 文件ID (路径参数)

4. Messages 模块 (消息管理)

4.1 根据话题ID数组统计消息数量

功能: 根据话题ID数组统计消息数量
请求方式: POST
请求路径: /api/v1/messages/count/by-topics
权限要求: 消息读取权限 (ALL, WORKSPACE, OWNER)
参数: 话题ID数组请求体

4.2 根据用户ID统计消息数量

功能: 根据用户ID统计消息数量
请求方式: POST
请求路径: /api/v1/messages/count/by-user
权限要求: 消息读取权限 (仅管理员)
参数: 用户ID请求体

4.3 根据话题ID获取消息列表

功能: 根据话题ID获取消息列表
请求方式: GET
请求路径: /api/v1/messages/queryByTopic/:topicId
权限要求: 消息读取权限 (ALL, WORKSPACE, OWNER)
参数: 话题ID (路径参数)

4.4 根据关键词搜索消息及对应话题

功能: 根据关键词搜索消息及对应话题
请求方式: GET
请求路径: /api/v1/messages/search
权限要求: 消息读取权限 (ALL, WORKSPACE, OWNER)
查询参数: 搜索关键词

4.5 根据消息ID获取消息详情

功能: 根据消息ID获取消息详情
请求方式: GET
请求路径: /api/v1/messages/:id
权限要求: 消息读取权限 (ALL, WORKSPACE, OWNER)
参数: 消息ID (路径参数)

4.6 创建新消息

功能: 创建新消息
请求方式: POST
请求路径: /api/v1/messages
权限要求: 消息创建权限 (ALL, WORKSPACE, OWNER)
参数: 消息创建请求体

4.7 创建用户消息并生成AI回复

功能: 创建用户消息并生成AI回复
请求方式: POST
请求路径: /api/v1/messages/reply
权限要求: 消息创建权限 (ALL, WORKSPACE, OWNER)
参数: 消息创建请求体

5. Message-Translates 模块 (消息翻译)

5.1 获取指定消息的翻译信息

功能: 获取指定消息的翻译信息
请求方式: GET
请求路径: /api/v1/message-translates/:messageId
权限要求: 消息读取权限 (ALL, WORKSPACE, OWNER)
参数: 消息ID (路径参数)

5.2 翻译指定消息

功能: 翻译指定消息
请求方式: POST
请求路径: /api/v1/message-translates
权限要求: 消息更新权限 (ALL, WORKSPACE, OWNER)
参数: 消息翻译触发请求体

5.3 更新消息翻译信息

功能: 更新消息翻译信息
请求方式: PUT
请求路径: /api/v1/message-translates/:messageId
权限要求: 消息更新权限 (ALL, WORKSPACE, OWNER)
参数: 消息ID (路径参数) + 翻译信息更新请求体

6. Models 模块 (模型管理)

6.1 获取模型列表

功能: 获取模型列表，支持分页、过滤和分组
请求方式: GET
请求路径: /api/v1/models
权限要求: AI模型读取权限 (ALL, WORKSPACE, OWNER)
查询参数: 模型查询参数 (分页、过滤等)

6.2 获取模型配置

功能: 获取模型配置信息
请求方式: GET
请求路径: /api/v1/models/config
权限要求: AI模型读取权限 (ALL, WORKSPACE, OWNER)
查询参数: 模型配置查询参数

6.3 根据会话获取模型配置

功能: 根据会话获取模型配置
请求方式: GET
请求路径: /api/v1/models/configBySession
权限要求: AI模型读取权限 (ALL, WORKSPACE, OWNER)
查询参数: 会话相关的模型配置查询参数

7. Roles 模块 (角色管理)

7.1 获取系统中所有角色

功能: 获取系统中所有角色
请求方式: GET
请求路径: /api/v1/roles
权限要求: 角色读取权限 (ALL, WORKSPACE)

7.2 获取系统中所有活跃角色

功能: 获取系统中所有活跃角色
请求方式: GET
请求路径: /api/v1/roles/active
权限要求: 角色读取权限 (ALL, WORKSPACE)

7.3 根据ID获取角色详情

功能: 根据ID获取角色详情
请求方式: GET
请求路径: /api/v1/roles/:id
权限要求: 角色读取权限 (ALL, WORKSPACE)
参数: 角色ID (路径参数)

7.4 获取角色权限映射

功能: 获取角色权限映射关系
请求方式: GET
请求路径: /api/v1/roles/:id/permissions
权限要求: 角色读取权限 (ALL, WORKSPACE)
参数: 角色ID (路径参数)

7.5 更新角色信息

功能: 更新角色信息
请求方式: PUT
请求路径: /api/v1/roles/:id
权限要求: 角色更新权限 (ALL, WORKSPACE)
参数: 角色ID (路径参数) + 角色更新请求体

8. Session-Groups 模块 (会话组管理)

8.1 获取会话组列表

功能: 获取会话组列表
请求方式: GET
请求路径: /api/v1/session-groups
权限要求: 会话组读取权限 (ALL, WORKSPACE, OWNER)

8.2 创建会话组

功能: 创建新的会话组
请求方式: POST
请求路径: /api/v1/session-groups
权限要求: 会话组创建权限 (ALL, WORKSPACE)
参数: 会话组创建请求体

8.3 更新会话组排序

功能: 更新会话组排序
请求方式: PUT
请求路径: /api/v1/session-groups/order
权限要求: 会话组更新权限 (ALL, WORKSPACE)
参数: 会话组排序更新请求体

8.4 根据ID获取会话组详情

功能: 根据ID获取会话组详情
请求方式: GET
请求路径: /api/v1/session-groups/:id
权限要求: 会话组读取权限 (ALL, WORKSPACE, OWNER)
参数: 会话组ID (路径参数)

8.5 更新会话组

功能: 更新会话组信息
请求方式: PUT
请求路径: /api/v1/session-groups/:id
权限要求: 会话组更新权限 (ALL, WORKSPACE, OWNER)
参数: 会话组ID (路径参数) + 会话组更新请求体

8.6 删除会话组

功能: 删除会话组，组内会话变为未分组状态
请求方式: DELETE
请求路径: /api/v1/session-groups/:id
权限要求: 会话组删除权限 (ALL, WORKSPACE, OWNER)
参数: 会话组ID (路径参数)

8.7 删除所有会话组

功能: 删除所有会话组
请求方式: DELETE
请求路径: /api/v1/session-groups
权限要求: 会话组删除权限 (ALL, WORKSPACE)

9. Sessions 模块 (会话管理)

9.1 获取会话列表

功能: 获取会话列表
请求方式: GET
请求路径: /api/v1/sessions
权限要求: 会话读取权限 (ALL, WORKSPACE, OWNER)
查询参数: 会话查询参数

9.2 获取分组的会话列表

功能: 获取分组的会话列表
请求方式: GET
请求路径: /api/v1/sessions/grouped
权限要求: 会话读取权限 (ALL, WORKSPACE, OWNER)

9.3 获取按Agent分组的会话数量

功能: 获取按Agent分组的会话数量统计
请求方式: GET
请求路径: /api/v1/sessions/grouped-by-agent
权限要求: 会话读取权限 (ALL, WORKSPACE, OWNER)

9.4 搜索会话

功能: 根据关键词搜索会话
请求方式: GET
请求路径: /api/v1/sessions/search
权限要求: 会话读取权限 (ALL, WORKSPACE, OWNER)
查询参数: 搜索关键词

9.5 创建会话

功能: 创建新的会话
请求方式: POST
请求路径: /api/v1/sessions
权限要求: 会话创建权限 (ALL, WORKSPACE)
参数: 会话创建请求体

9.6 根据ID获取会话详情

功能: 根据ID获取会话详情
请求方式: GET
请求路径: /api/v1/sessions/:id
权限要求: 会话读取权限 (ALL, WORKSPACE, OWNER)
参数: 会话ID (路径参数)

9.7 批量查询指定的会话

功能: 根据会话ID列表批量查询会话
请求方式: POST
请求路径: /api/v1/sessions/batch
权限要求: 会话读取权限 (ALL, WORKSPACE)
参数: 会话ID列表请求体

9.8 批量更新会话

功能: 批量更新多个会话
请求方式: PUT
请求路径: /api/v1/sessions/batch-update
权限要求: 会话更新权限 (ALL, WORKSPACE, OWNER)
参数: 批量更新请求体

9.9 更新会话

功能: 更新会话信息
请求方式: PUT
请求路径: /api/v1/sessions/:id
权限要求: 会话更新权限 (ALL, WORKSPACE, OWNER)
参数: 会话ID (路径参数) + 会话更新请求体

9.10 删除会话

功能: 删除指定会话
请求方式: DELETE
请求路径: /api/v1/sessions/:id
权限要求: 会话删除权限 (ALL, WORKSPACE, OWNER)
参数: 会话ID (路径参数)

9.11 克隆会话

功能: 克隆现有会话创建新会话
请求方式: POST
请求路径: /api/v1/sessions/:id/clone
权限要求: 会话创建权限 (ALL, WORKSPACE)
参数: 会话ID (路径参数) + 克隆请求体

9.12 更新会话分组关联

功能: 更新会话的分组关联关系
请求方式: PUT
请求路径: /api/v1/sessions/:id/group
权限要求: 会话更新权限 (ALL, WORKSPACE, OWNER)
参数: 会话ID (路径参数) + 分组关联更新请求体

10. Topics 模块 (话题管理)

10.1 创建新的话题

功能: 创建新的话题
请求方式: POST
请求路径: /api/v1/topics
权限要求: 话题创建权限 (ALL, WORKSPACE, OWNER)
参数: 话题创建请求体

10.2 获取指定话题

功能: 根据话题ID获取话题详情
请求方式: GET
请求路径: /api/v1/topics/:id
权限要求: 话题读取权限 (ALL, WORKSPACE, OWNER)
参数: 话题ID (路径参数)

10.3 更新话题

功能: 更新话题信息
请求方式: PUT
请求路径: /api/v1/topics/:id
权限要求: 话题更新权限 (ALL, WORKSPACE, OWNER)
参数: 话题ID (路径参数) + 话题更新请求体

10.4 删除话题

功能: 删除指定话题
请求方式: DELETE
请求路径: /api/v1/topics/:id
权限要求: 话题删除权限 (ALL, WORKSPACE, OWNER)
参数: 话题ID (路径参数)

10.5 获取指定会话的所有话题

功能: 根据会话ID获取该会话的所有话题
请求方式: GET
请求路径: /api/v1/topics/session/:sessionId
权限要求: 话题读取权限 (ALL, WORKSPACE, OWNER)
参数: 会话ID (路径参数) + 查询参数

10.6 总结对应的话题标题

功能: 使用AI总结话题标题
请求方式: POST
请求路径: /api/v1/topics/summary-title
权限要求: 话题更新权限 (ALL, WORKSPACE, OWNER)
参数: 话题总结请求体

11. Users 模块 (用户管理)

11.1 获取当前登录用户信息

功能: 获取当前登录用户信息
请求方式: GET
请求路径: /api/v1/users/me
权限要求: 需要认证，但不需要特殊权限

11.2 获取系统中所有用户列表

功能: 获取系统中所有用户列表
请求方式: GET
请求路径: /api/v1/users
权限要求: 用户读取权限 (ALL, WORKSPACE)

11.3 创建新用户

功能: 创建新用户
请求方式: POST
请求路径: /api/v1/users
权限要求: 用户创建权限 (ALL, WORKSPACE)
参数: 用户创建请求体

11.4 搜索用户

功能: 根据关键词搜索用户
请求方式: GET
请求路径: /api/v1/users/search
权限要求: 用户读取权限 (ALL, WORKSPACE)
查询参数: keyword (搜索关键词)

11.5 获取用户角色信息

功能: 获取用户的角色信息
请求方式: GET
请求路径: /api/v1/users/:id/roles
权限要求: 用户角色查看权限 (ALL, WORKSPACE)
参数: 用户ID (路径参数)

11.6 更新用户关联的角色

功能: 更新用户关联的角色
请求方式: PUT
请求路径: /api/v1/users/:id/roles
权限要求: 用户角色分配权限 (ALL, WORKSPACE)
参数: 用户ID (路径参数) + 角色更新请求体

11.7 根据ID获取用户详情

功能: 根据ID获取用户详情
请求方式: GET
请求路径: /api/v1/users/:id
权限要求: 用户读取权限 (ALL, WORKSPACE, OWNER)
参数: 用户ID (路径参数)

11.8 更新用户信息

功能: 更新用户信息
请求方式: PUT
请求路径: /api/v1/users/:id
权限要求: 用户更新权限 (ALL, WORKSPACE, OWNER)
参数: 用户ID (路径参数) + 用户更新请求体

11.9 删除用户

功能: 删除用户
请求方式: DELETE
请求路径: /api/v1/users/:id
权限要求: 用户删除权限 (ALL, WORKSPACE)
参数: 用户ID (路径参数)

接口统计总结

模块	接口数量	主要功能
Agents	6	智能体的 CRUD 操作和查询
Chat	3	聊天、翻译、生成回复
Files	11	文件上传、下载、解析、管理
Messages	7	消息的创建、查询、统计、搜索
Message-Translates	3	消息翻译功能
Models	3	模型列表和配置管理
Roles	5	角色和权限管理
Session-Groups	7	会话组的 CRUD 操作
Sessions	12	会话的完整生命周期管理
Topics	6	话题的 CRUD 操作和总结
Users	9	用户管理和角色分配
总计	72	完整的 AI 聊天应用功能

权限系统说明

权限范围

ALL: 全局权限，通常为超级管理员
WORKSPACE: 工作空间权限，工作空间管理员
OWNER: 所有者权限，资源创建者

权限类型

READ: 读取权限
CREATE: 创建权限
UPDATE: 更新权限
DELETE: 删除权限

特殊权限

RBAC_*: 角色和权限管理相关权限
AI_MODEL_*: AI模型相关权限

文档生成时间: 2024年
基于 LobeChat 项目路由文件分析生成

MarioJames · 2025-08-05T10:03:11Z

MarioJames
Aug 5, 2025
Author

关联 PR

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[RFC] 126 - LobeChat OpenAPI #8679

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

[RFC] 126 - LobeChat OpenAPI #8679

Uh oh!

MarioJames Aug 5, 2025

LobeChat API 接口文档

概述

认证说明

1. Agents 模块 (智能体管理)

1.1 获取系统中所有的 Agent 列表

1.2 创建智能体

1.3 更新智能体

1.4 删除智能体

1.5 根据 ID 获取 Agent 详情

1.6 根据 Session ID 获取关联的 Agent 详情

2. Chat 模块 (聊天功能)

2.1 通用聊天接口

2.2 翻译接口

2.3 生成回复接口

3. Files 模块 (文件管理)

3.1 获取文件列表

3.2 单文件上传

3.3 批量文件上传

3.4 公共文件上传

3.5 获取文件详情

3.6 获取文件访问URL

3.7 获取文件永久访问URL

3.8 解析文件内容

3.9 上传文件并解析文件内容

3.10 批量获取文件详情和内容

3.11 删除文件

4. Messages 模块 (消息管理)

4.1 根据话题ID数组统计消息数量

4.2 根据用户ID统计消息数量

4.3 根据话题ID获取消息列表

4.4 根据关键词搜索消息及对应话题

4.5 根据消息ID获取消息详情

4.6 创建新消息

4.7 创建用户消息并生成AI回复

5. Message-Translates 模块 (消息翻译)

5.1 获取指定消息的翻译信息

5.2 翻译指定消息

5.3 更新消息翻译信息

6. Models 模块 (模型管理)

6.1 获取模型列表

6.2 获取模型配置

6.3 根据会话获取模型配置

7. Roles 模块 (角色管理)

7.1 获取系统中所有角色

7.2 获取系统中所有活跃角色

7.3 根据ID获取角色详情

7.4 获取角色权限映射

7.5 更新角色信息

8. Session-Groups 模块 (会话组管理)

8.1 获取会话组列表

8.2 创建会话组

8.3 更新会话组排序

8.4 根据ID获取会话组详情

8.5 更新会话组

8.6 删除会话组

8.7 删除所有会话组

9. Sessions 模块 (会话管理)

9.1 获取会话列表

9.2 获取分组的会话列表

9.3 获取按Agent分组的会话数量

9.4 搜索会话

9.5 创建会话

9.6 根据ID获取会话详情

9.7 批量查询指定的会话

9.8 批量更新会话

9.9 更新会话

9.10 删除会话

9.11 克隆会话

9.12 更新会话分组关联

10. Topics 模块 (话题管理)

10.1 创建新的话题

10.2 获取指定话题

10.3 更新话题

10.4 删除话题

10.5 获取指定会话的所有话题

10.6 总结对应的话题标题

MarioJames
Aug 5, 2025

MarioJames
Aug 5, 2025
Author