458 lines
10 KiB
Markdown
458 lines
10 KiB
Markdown
# 海角AI - API接口文档
|
||
|
||
## 用户认证模块
|
||
|
||
### 用户登录 1111
|
||
|
||
**功能描述**: 用户通过邮箱和密码进行登录认证，登录成功后返回token和用户基本信息
|
||
|
||
**入参**:
|
||
- `email`: string - 用户邮箱地址
|
||
- `password`: string - 用户密码
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.token`: string - 访问令牌
|
||
- `body.user`: object - 用户信息对象
|
||
- `body.user.id`: int - 用户ID
|
||
- `body.user.nickname`: string - 用户昵称
|
||
- `body.user.email`: string - 用户邮箱
|
||
- `body.user.avatar`: string - 用户头像URL
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/auth/login
|
||
**请求方式**: POST
|
||
|
||
---
|
||
|
||
### 用户注册
|
||
|
||
**功能描述**: 新用户注册，创建账户并返回用户信息
|
||
|
||
**入参**:
|
||
- `email`: string - 用户邮箱地址
|
||
- `password`: string - 用户密码
|
||
- `nickname`: string - 用户昵称
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.user_id`: int - 新创建的用户ID
|
||
- `body.token`: string - 访问令牌
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/auth/register
|
||
**请求方式**: POST
|
||
|
||
---
|
||
|
||
### 用户登出
|
||
|
||
**功能描述**: 用户登出，使当前token失效
|
||
|
||
**入参**: 无
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/auth/logout
|
||
**请求方式**: POST
|
||
|
||
---
|
||
|
||
### 获取用户信息
|
||
|
||
**功能描述**: 获取当前登录用户的详细信息
|
||
|
||
**入参**: 无（通过Authorization Header传递token）
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.user_id`: int - 用户ID
|
||
- `body.nickname`: string - 用户昵称
|
||
- `body.email`: string - 用户邮箱
|
||
- `body.avatar`: string - 用户头像URL
|
||
- `body.created_at`: int - 注册时间戳
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/user/info
|
||
**请求方式**: GET
|
||
|
||
---
|
||
|
||
## 聊天模块
|
||
|
||
### 创建会话
|
||
|
||
**功能描述**: 创建新的聊天会话，用于组织对话
|
||
|
||
**入参**:
|
||
- `title`: string - 会话标题
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.session_id`: string - 会话ID
|
||
- `body.title`: string - 会话标题
|
||
- `body.created_at`: int - 创建时间戳
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/chat/session
|
||
**请求方式**: POST
|
||
|
||
---
|
||
|
||
### 发送消息
|
||
|
||
**功能描述**: 向指定会话发送消息，AI会根据消息内容和配置参数生成回复
|
||
|
||
**入参**:
|
||
- `session_id`: string - 会话ID
|
||
- `content`: string - 消息内容
|
||
- `model`: string - 使用的AI模型，默认为"Hunyuan"
|
||
- `deep_thinking`: bool - 是否启用深度思考模式
|
||
- `web_search`: bool - 是否启用联网搜索
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.user_message_id`: string - 用户消息ID
|
||
- `body.ai_response`: object - AI回复对象
|
||
- `body.ai_response.id`: string - AI消息ID
|
||
- `body.ai_response.content`: string - AI回复内容
|
||
- `body.ai_response.timestamp`: int - 回复时间戳
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/chat/send
|
||
**请求方式**: POST
|
||
|
||
---
|
||
|
||
### 获取会话列表
|
||
|
||
**功能描述**: 获取用户的所有聊天会话列表，支持分页和关键词搜索
|
||
|
||
**入参**:
|
||
- `page`: int - 页码（默认1）
|
||
- `page_size`: int - 每页数量（默认20）
|
||
- `keyword`: string - 搜索关键词（可选）
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.sessions`: array - 会话列表
|
||
- `body.sessions[].id`: string - 会话ID
|
||
- `body.sessions[].title`: string - 会话标题
|
||
- `body.sessions[].message_count`: int - 消息数量
|
||
- `body.sessions[].last_message_time`: int - 最后消息时间戳
|
||
- `body.total`: int - 总数量
|
||
- `body.has_more`: bool - 是否还有更多
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/chat/sessions
|
||
**请求方式**: GET
|
||
|
||
---
|
||
|
||
### 获取会话消息
|
||
|
||
**功能描述**: 获取指定会话的消息历史记录，支持分页
|
||
|
||
**入参**:
|
||
- `session_id`: string - 会话ID
|
||
- `page`: int - 页码（默认1）
|
||
- `page_size`: int - 每页数量（默认50）
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.messages`: array - 消息列表
|
||
- `body.messages[].id`: string - 消息ID
|
||
- `body.messages[].role`: string - 消息角色（user/assistant）
|
||
- `body.messages[].content`: string - 消息内容
|
||
- `body.messages[].timestamp`: int - 消息时间戳
|
||
- `body.messages[].is_favorited`: bool - 是否已收藏
|
||
- `body.total`: int - 总数量
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/chat/messages
|
||
**请求方式**: GET
|
||
|
||
---
|
||
|
||
### 删除会话
|
||
|
||
**功能描述**: 删除指定的聊天会话及其所有消息
|
||
|
||
**入参**: 无（会话ID通过URL路径传递）
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/chat/session/{session_id}
|
||
**请求方式**: DELETE
|
||
|
||
---
|
||
|
||
### 清空会话
|
||
|
||
**功能描述**: 清空指定会话的所有消息，但保留会话本身
|
||
|
||
**入参**: 无（会话ID通过URL路径传递）
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/chat/session/{session_id}/clear
|
||
**请求方式**: POST
|
||
|
||
---
|
||
|
||
## 收藏模块
|
||
|
||
### 收藏消息
|
||
|
||
**功能描述**: 将指定消息添加到收藏列表
|
||
|
||
**入参**:
|
||
- `message_id`: string - 消息ID
|
||
- `session_id`: string - 会话ID
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.favorite_id`: string - 收藏记录ID
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/favorites/add
|
||
**请求方式**: POST
|
||
|
||
---
|
||
|
||
### 取消收藏
|
||
|
||
**功能描述**: 从收藏列表中移除指定消息
|
||
|
||
**入参**:
|
||
- `message_id`: string - 消息ID
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/favorites/remove
|
||
**请求方式**: DELETE
|
||
|
||
---
|
||
|
||
### 获取收藏列表
|
||
|
||
**功能描述**: 获取用户的所有收藏消息列表，支持分页
|
||
|
||
**入参**:
|
||
- `page`: int - 页码（默认1）
|
||
- `page_size`: int - 每页数量（默认20）
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.favorites`: array - 收藏列表
|
||
- `body.favorites[].id`: string - 收藏记录ID
|
||
- `body.favorites[].message_id`: string - 消息ID
|
||
- `body.favorites[].content`: string - 消息内容
|
||
- `body.favorites[].session_title`: string - 所属会话标题
|
||
- `body.favorites[].created_at`: int - 收藏时间戳
|
||
- `body.total`: int - 总数量
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/favorites/list
|
||
**请求方式**: GET
|
||
|
||
---
|
||
|
||
## 文件上传模块
|
||
|
||
### 上传文件
|
||
|
||
**功能描述**: 上传文件（支持txt、pdf、md等格式）用于AI分析和处理
|
||
|
||
**入参**:
|
||
- `file`: file - 上传的文件
|
||
- `session_id`: string - 关联的会话ID
|
||
|
||
**返回参数**:
|
||
- `error`: int - 错误码，0表示成功
|
||
- `body`: object - 响应数据
|
||
- `body.file_id`: string - 文件ID
|
||
- `body.filename`: string - 文件名
|
||
- `body.file_size`: int - 文件大小（字节）
|
||
- `body.file_type`: string - 文件类型
|
||
- `body.upload_time`: int - 上传时间戳
|
||
- `message`: string - 响应消息
|
||
- `success`: bool - 是否成功
|
||
|
||
**url地址**: /api/files/upload
|
||
**请求方式**: POST
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 0 | 成功 |
|
||
| 1001 | 参数错误 |
|
||
| 1002 | 用户不存在 |
|
||
| 1003 | 密码错误 |
|
||
| 1004 | 邮箱已存在 |
|
||
| 1005 | Token无效或已过期 |
|
||
| 2001 | 会话不存在 |
|
||
| 2002 | 消息发送失败 |
|
||
| 2003 | 文件上传失败 |
|
||
| 2004 | 文件格式不支持 |
|
||
| 2005 | 文件大小超出限制 |
|
||
| 3001 | 收藏失败 |
|
||
| 3002 | 收藏记录不存在 |
|
||
| 5000 | 服务器内部错误 |
|
||
| 5001 | AI服务不可用 |
|
||
| 5002 | 网络搜索服务不可用 |
|
||
|
||
---
|
||
|
||
## 通用响应格式
|
||
|
||
所有API接口都采用统一的响应格式：
|
||
|
||
```json
|
||
{
|
||
"error": 0,
|
||
"body": {
|
||
// 具体的响应数据
|
||
},
|
||
"message": "操作成功",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
## 认证说明
|
||
|
||
除了登录和注册接口外，其他接口都需要在请求头中携带Authorization：
|
||
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
## 基础信息
|
||
|
||
- **基础URL**: http://localhost:8080
|
||
- **超时时间**: 10秒
|
||
- **默认Content-Type**: application/json
|
||
- **支持的AI模型**: Hunyuan、基础模型、增强模型
|
||
|
||
## 请求示例
|
||
|
||
### 登录请求示例
|
||
|
||
```javascript
|
||
// 请求
|
||
POST /api/auth/login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"email": "user@example.com",
|
||
"password": "password123"
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"error": 0,
|
||
"body": {
|
||
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
|
||
"user": {
|
||
"id": 1,
|
||
"nickname": "用户昵称",
|
||
"email": "user@example.com",
|
||
"avatar": "https://example.com/avatar.jpg"
|
||
}
|
||
},
|
||
"message": "登录成功",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 发送消息请求示例
|
||
|
||
```javascript
|
||
// 请求
|
||
POST /api/chat/send
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"session_id": "session_123",
|
||
"content": "你好，请帮我解释一下Vue3的组合式API",
|
||
"model": "Hunyuan",
|
||
"deep_thinking": true,
|
||
"web_search": false
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"error": 0,
|
||
"body": {
|
||
"user_message_id": "msg_456",
|
||
"ai_response": {
|
||
"id": "msg_789",
|
||
"content": "Vue3的组合式API是一种新的组织组件逻辑的方式...",
|
||
"timestamp": 1692345678
|
||
}
|
||
},
|
||
"message": "消息发送成功",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 文件上传请求示例
|
||
|
||
```javascript
|
||
// 请求
|
||
POST /api/files/upload
|
||
Authorization: Bearer <token>
|
||
Content-Type: multipart/form-data
|
||
|
||
FormData:
|
||
- file: [选择的文件]
|
||
- session_id: "session_123"
|
||
|
||
// 响应
|
||
{
|
||
"error": 0,
|
||
"body": {
|
||
"file_id": "file_456",
|
||
"filename": "document.pdf",
|
||
"file_size": 1024000,
|
||
"file_type": "application/pdf",
|
||
"upload_time": 1692345678
|
||
},
|
||
"message": "文件上传成功",
|
||
"success": true
|
||
}
|
||
``` |