lxy/hs-end
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
hs-end/api.md
lxy e559cd4e79 two 
2
2025-08-25 16:09:36 +08:00

10 KiB
Raw Permalink Blame History

海角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接口都采用统一的响应格式：

{
  "error": 0,
  "body": {
    // 具体的响应数据
  },
  "message": "操作成功",
  "success": true
}

认证说明

除了登录和注册接口外，其他接口都需要在请求头中携带Authorization：

Authorization: Bearer <token>

基础信息

  • 基础URL: http://localhost:8080
  • 超时时间: 10秒
  • 默认Content-Type: application/json
  • 支持的AI模型: Hunyuan、基础模型、增强模型

请求示例

登录请求示例

// 请求
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
}

发送消息请求示例

// 请求
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
}

文件上传请求示例

// 请求
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
}