# 前端接口

适合二开，使用burncloud作为供应商，包含用户余额，积分记录，任务记录，token余额等等，满足二开，建立服务后端。

# 鉴权体系说明（Auth）

## 说明

系统采用四级鉴权机制：公开、用户、管理员、Root

## 🔐 鉴权

- **公开**：无需登录
- **用户**：需要用户 Token （middleware.UserAuth）
- **管理员**：需要管理员 Token （middleware.AdminAuth）
- **Root**：仅限最高权限用户 （middleware.RootAuth）

# 获取可用模型列表（Model）

## 说明

接口前缀统一为 `http(s)://<your-domain>`

生产环境应使用 HTTPS 以保证认证令牌。HTTP 仅建议用于开发环境。

## 接口信息
- **接口名称**：获取前端可用模型列表
- **HTTP 方法**：GET
- **路径**：`/api/models`
- **鉴权要求**：用户
- **功能简介**：获取当前用户可访问的 AI 模型列表，用于前端 Dashboard 展示

## 💡 请求示例

```javascript
const response = await fetch('/api/models', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

## ✅ 成功响应示例

```json
{  
  "success": true,  
  "data": {  
    "1": ["gpt-3.5-turbo", "gpt-4"],  
    "2": ["claude-3-sonnet", "claude-3-haiku"]  
  }  
}
```

## ❗ 失败响应示例

```json
{  
  "success": false,  
  "message": "未授权访问"  
}
```

## 🧾 字段说明

- **data** （对象）: 渠道 ID 到模型列表的映射
  - **键** （字符串）: 渠道 ID
  - **值** （数组）: 该渠道支持的模型名称列表

# 公共信息模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

提供无需认证或低权限访问的系统信息，包括模型列表、定价信息、公告内容等。支持多语言显示和动态配置。前端首页和模型广场主要依赖这些接口获取展示数据。

## 🔐 无需鉴权

### 获取公告栏内容

- **接口名称**：获取公告栏内容
- **HTTP 方法**：GET
- **路径**：`/api/notice`
- **鉴权要求**：公开
- **功能简介**：获取系统公告内容，支持 Markdown 格式

#### 💡 请求示例：

```javascript
const response = await fetch('/api/notice', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": "# 系统公告\n\n欢迎使用New API系统！"  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取公告失败"  
}
```

#### 🧾 字段说明：

- **data** （字符串）: 公告内容，支持 Markdown 格式

### 关于页面信息

- **接口名称**：关于页面信息
- **HTTP 方法**：GET
- **路径**：`/api/about`
- **鉴权要求**：公开
- **功能简介**：获取关于页面的自定义内容

#### 💡 请求示例：

```javascript
const response = await fetch('/api/about', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": "# 关于我们\n\nNew API是一个强大的AI网关系统..."  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取关于信息失败"  
}
```

#### 🧾 字段说明：

- **data** （字符串）: 关于页面内容，支持 Markdown 格式或 URL 链接

### 首页自定义内容

- **接口名称**：首页自定义内容
- **HTTP 方法**：GET
- **路径**：`/api/home_page_content`
- **鉴权要求**：公开
- **功能简介**：获取首页的自定义内容，可以是 Markdown 文本或 iframe URL

#### 💡 请求示例：

```javascript
const response = await fetch('/api/home_page_content', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": "# 欢迎使用New API\n\n这是一个功能强大的AI网关系统..."  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取首页内容失败"  
}
```

#### 🧾 字段说明：

- **data** （字符串）: 首页内容，可以是 Markdown 文本或以"https://"开头的 URL 链接

### 模型倍率配置

- **接口名称**：模型倍率配置
- **HTTP 方法**：GET
- **路径**：`/api/ratio_config`
- **鉴权要求**：公开
- **功能简介**：获取公开的模型倍率配置信息，用于上游系统同步

#### 💡 请求示例：

```javascript
const response = await fetch('/api/ratio_config', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "data": {  
    "model_ratio": {  
      "gpt-3.5-turbo": 1.0,  
      "gpt-4": 15.0,  
      "claude-3-sonnet": 3.0  
    },  
    "completion_ratio": {  
      "gpt-3.5-turbo": 1.0,  
      "gpt-4": 1.0  
    },  
    "model_price": {  
      "gpt-3.5-turbo-instruct": 0.002  
    }  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取倍率配置失败"  
}
```

#### 🧾 字段说明：

- **data** （对象）: 倍率配置信息
  - **model_ratio** （对象）: 模型倍率映射，键为模型名，值为倍率数值
  - **completion_ratio** （对象）: 补全倍率映射
  - **model_price** （对象）: 模型价格映射，键为模型名，值为价格（美元）

### 价格与套餐信息

- **接口名称**：价格与套餐信息
- **HTTP 方法**：GET
- **路径**：`/api/pricing`
- **鉴权要求**：可匿名/用户
- **功能简介**：获取模型定价信息、分组倍率和可用分组

#### 💡 请求示例：

```javascript
const response = await fetch('/api/pricing', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_token', // 可选，登录用户可获得更详细信息
    'New-Api-User': 'Bearer your_user_id' // 可选
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "data": [  
    {  
      "model_name": "gpt-3.5-turbo",  
      "enable_group": ["default", "vip"],  
      "model_ratio": 1.0,  
      "completion_ratio": 1.0,  
      "model_price": 0.002,  
      "quota_type": 1,  
      "description": "GPT-3.5 Turbo模型",  
      "vendor_id": 1,  
      "supported_endpoint_types": [1, 2]  
    }  
  ],  
  "vendors": [  
    {  
      "id": 1,  
      "name": "OpenAI",  
      "description": "OpenAI官方模型",  
      "icon": "openai.png"  
    }  
  ],  
  "group_ratio": {  
    "default": 1.0,  
    "vip": 0.8  
  },  
  "usable_group": {  
    "default": "默认分组",  
    "vip": "VIP分组"  
  },  
  "supported_endpoint": {  
    "1": {"method": "POST", "path": "/v1/chat/completions"},  
    "2": {"method": "POST", "path": "/v1/embeddings"}  
  },  
  "auto_groups": ["default"]  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取定价信息失败"  
}
```

#### 🧾 字段说明：

- **data** （数组）: 模型定价信息列表
  - **model_name** （字符串）: 模型名称
  - **enable_group** （数组）: 可用分组列表
  - **model_ratio** （数字）: 模型倍率
  - **completion_ratio** （数字）: 补全倍率
  - **model_price** （数字）: 模型价格（美元）
  - **quota_type** （数字）: 计费类型，0=倍率计费，1=价格计费
  - **description** （字符串）: 模型描述
  - **vendor_id** （数字）: 供应商 ID
  - **supported_endpoint_types** （数组）: 支持的端点类型
- **vendors** （数组）: 供应商信息列表
  - **id** （数字）: 供应商 ID
  - **name** （字符串）: 供应商名称
  - **description** （字符串）: 供应商描述
  - **icon** （字符串）: 供应商图标
- **group_ratio** （对象）: 分组倍率映射
- **usable_group** （对象）: 可用分组映射
- **supported_endpoint** （对象）: 支持的端点信息
- **auto_groups** （数组）: 自动分组列表

## 🔐 用户鉴权

### 获取前端可用模型列表

- **接口名称**：获取前端可用模型列表
- **HTTP 方法**：GET
- **路径**：`/api/models`
- **鉴权要求**：用户
- **功能简介**：获取当前用户可访问的 AI 模型列表，用于前端 Dashboard 展示

#### 💡 请求示例：

```javascript
const response = await fetch('/api/models', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "data": {  
    "1": ["gpt-3.5-turbo", "gpt-4"],  
    "2": ["claude-3-sonnet", "claude-3-haiku"]  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "未授权访问"  
}
```

#### 🧾 字段说明：

- **data** （对象）: 渠道 ID 到模型列表的映射
  - **键** （字符串）: 渠道 ID
  - **值** （数组）: 该渠道支持的模型名称列表

# 邮箱身份验证模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

实现邮箱验证和密码重置功能，集成限流和 Turnstile 防护。支持自动生成随机密码和邮件模板定制。在用户注册、账户绑定等场景中广泛使用。

## 🔐 无需鉴权

### 发送邮箱验证邮件

- **接口名称**：发送邮箱验证邮件
- **HTTP 方法**：GET
- **路径**：`/api/verification`
- **鉴权要求**：公开 （限流）
- **功能简介**：发送邮箱验证码到指定邮箱地址，用于邮箱绑定或验证操作

#### 💡 请求示例：

```javascript
const response = await fetch(`/api/verification?email=${email}&turnstile=${turnstileToken}`, {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "无效的参数"  
}
```

#### 🧾 字段说明：

- **email** （字符串）: 接收验证码的邮箱地址，必须是有效的邮箱格式
- **turnstile** （字符串）: Turnstile 验证令牌，用于防止机器人攻击

### 发送重置密码邮件

- **接口名称**：发送重置密码邮件
- **HTTP 方法**：GET
- **路径**：`/api/reset_password`
- **鉴权要求**：公开 （限流）
- **功能简介**：向已注册邮箱发送密码重置链接，用于用户找回密码

#### 💡 请求示例：

```javascript
const response = await fetch(`/api/reset_password?email=${email}&turnstile=${turnstileToken}`, {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "该邮箱地址未注册"  
}
```

#### 🧾 字段说明：

- **email** （字符串）: 需要重置密码的邮箱地址，必须是已注册的邮箱
- **turnstile** （字符串）: Turnstile 验证令牌，用于防止恶意请求

### 提交重置密码请求

- **接口名称**：提交重置密码请求
- **HTTP 方法**：POST
- **路径**：`/api/user/reset`
- **鉴权要求**：公开
- **功能简介**：通过邮件中的重置链接完成密码重置，系统会生成新密码并返回

#### 💡 请求示例：

```javascript
const response = await fetch('/api/user/reset', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json'  
  },  
  body: JSON.stringify({  
    email: "user@example.com",  
    token: "verification_token_from_email"  
  })  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": "newPassword123"  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "重置链接非法或已过期"  
}
```

#### 🧾 字段说明：

- **email** （字符串）: 要重置密码的邮箱地址
- **token** （字符串）: 从重置邮件中获取的验证令牌
- **data** （字符串）: 成功时返回的新密码，系统自动生成 12 位随机密码

# OAuth 第三方登录模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

支持 GitHub、OIDC、LinuxDO、微信、Telegram 等多种 OAuth 登录方式。实现 CSRF 防护和会话管理，支持账户绑定和自动注册。前端通过重定向方式处理 OAuth 流程。

## 🔐 无需鉴权

### GitHub OAuth 跳转

- **接口名称**：GitHub OAuth 跳转
- **HTTP 方法**：GET
- **路径**：`/api/oauth/github`
- **鉴权要求**：公开
- **功能简介**：处理 GitHub OAuth 回调，完成用户登录或账户绑定

#### 💡 请求示例：

```javascript
// 前端通过重定向方式调用，通常由GitHub OAuth授权后自动回调
window.location.href = `https://github.com/login/oauth/authorize?client_id=${github_client_id}&state=${state}&scope=user:email`;
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "登录成功",  
  "data": {  
    "token": "user_access_token",  
    "user": {  
      "id": 1,  
      "username": "github_user",  
      "display_name": "GitHub User",  
      "email": "user@example.com"  
    }  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "管理员未开启通过 GitHub 登录以及注册"  
}
```

#### 🧾 字段说明：

- **code** （字符串）: GitHub OAuth 授权码，由 GitHub 回调时提供
- **state** （字符串）: 防 CSRF 状态码，必须与 session 中存储的一致

### OIDC 通用 OAuth 跳转

- **接口名称**：OIDC 通用 OAuth 跳转
- **HTTP 方法**：GET
- **路径**：`/api/oauth/oidc`
- **鉴权要求**：公开
- **功能简介**：处理 OIDC OAuth 回调，支持通用 OpenID Connect 协议登录

#### 💡 请求示例：

```javascript
// 前端通过重定向方式调用
const url = new URL(auth_url);  
url.searchParams.set('client_id', client_id);  
url.searchParams.set('redirect_uri', `${window.location.origin}/oauth/oidc`);  
url.searchParams.set('response_type', 'code');  
url.searchParams.set('scope', 'openid profile email');  
url.searchParams.set('state', state);  
window.location.href = url.toString();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "登录成功",  
  "data": {  
    "token": "user_access_token",  
    "user": {  
      "id": 1,  
      "username": "oidc_user",  
      "email": "user@example.com"  
    }  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "OIDC 获取用户信息失败！请检查设置！"  
}
```

#### 🧾 字段说明：

- **code** （字符串）: OIDC 授权码
- **state** （字符串）: 防 CSRF 状态码

### LinuxDo OAuth 跳转

- **接口名称**：LinuxDo OAuth 跳转
- **HTTP 方法**：GET
- **路径**：`/api/oauth/linuxdo`
- **鉴权要求**：公开
- **功能简介**：处理 LinuxDo OAuth 回调，支持通过 LinuxDo 社区账户登录

#### 💡 请求示例：

```javascript
// 前端通过重定向方式调用
window.location.href = `https://connect.linux.do/oauth2/authorize?response_type=code&client_id=${linuxdo_client_id}&state=${state}`;
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "登录成功",  
  "data": {  
    "token": "user_access_token",  
    "user": {  
      "id": 1,  
      "username": "linuxdo_user",  
      "display_name": "LinuxDo User"  
    }  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "管理员关闭了新用户注册"  
}
```

#### 🧾 字段说明：

- **code** （字符串）: LinuxDo OAuth 授权码
- **state** （字符串）: 防 CSRF 状态码
- **error** （字符串）: 可选，OAuth 错误码
- **error_description** （字符串）: 可选，错误描述

### 微信扫码登录跳转

- **接口名称**：微信扫码登录跳转
- **HTTP 方法**：GET
- **路径**：`/api/oauth/wechat`
- **鉴权要求**：公开
- **功能简介**：处理微信扫码登录，通过验证码完成登录流程

#### 💡 请求示例：

```javascript
const response = await fetch(`/api/oauth/wechat?code=${wechat_verification_code}`, {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "登录成功",  
  "data": {  
    "token": "user_access_token",  
    "user": {  
      "id": 1,  
      "username": "wechat_user",  
      "wechat_id": "wechat_openid"  
    }  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "验证码无效或已过期"  
}
```

#### 🧾 字段说明：

- **code** （字符串）: 微信扫码获得的验证码

### 微信账户绑定

- **接口名称**：微信账户绑定
- **HTTP 方法**：GET
- **路径**：`/api/oauth/wechat/bind`
- **鉴权要求**：公开
- **功能简介**：将微信账户绑定到现有用户账户

#### 💡 请求示例：

```javascript
const response = await fetch(`/api/oauth/wechat/bind?code=${wechat_verification_code}`, {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "微信账户绑定成功！"  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "验证码无效或该微信账户已被绑定"  
}
```

#### 🧾 字段说明：

- **code** （字符串）: 微信扫码获得的验证码

### 邮箱绑定

- **接口名称**：邮箱绑定
- **HTTP 方法**：GET
- **路径**：`/api/oauth/email/bind`
- **鉴权要求**：公开
- **功能简介**：通过邮箱验证码绑定邮箱到用户账户

#### 💡 请求示例：

```javascript
const response = await fetch(`/api/oauth/email/bind?email=${email}&code=${email_verification_code}`, {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "邮箱账户绑定成功！"  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "验证码无效或邮箱已被使用"  
}
```

#### 🧾 字段说明：

- **email** （字符串）: 要绑定的邮箱地址
- **code** （字符串）: 邮箱验证码

### Telegram 登录

- **接口名称**：Telegram 登录
- **HTTP 方法**：GET
- **路径**：`/api/oauth/telegram/login`
- **鉴权要求**：公开
- **功能简介**：通过 Telegram Widget 完成用户登录

#### 💡 请求示例：

```javascript
const params = {  
  id: telegram_user_id,  
  first_name: "John",  
  last_name: "Doe",   
  username: "johndoe",  
  photo_url: "https://...",  
  auth_date: 1640995200,  
  hash: "telegram_hash"  
};  
const query = new URLSearchParams(params).toString();
const response = await fetch(`/api/oauth/telegram/login?${query}`, {
  method: 'GET'
});
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "登录成功",  
  "data": {  
    "token": "user_access_token",  
    "user": {  
      "id": 1,  
      "username": "telegram_user",  
      "telegram_id": "123456789"  
    }  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "Telegram验证失败"  
}
```

#### 🧾 字段说明：

- **id** （字符串）: Telegram 用户 ID
- **first_name** （字符串）: 用户名字
- **last_name** （字符串）: 用户姓氏，可选
- **username** （字符串）: Telegram 用户名，可选
- **photo_url** （字符串）: 头像 URL，可选
- **auth_date** （数字）: 认证时间戳
- **hash** （字符串）: Telegram 验证哈希

### Telegram 账户绑定

- **接口名称**：Telegram 账户绑定
- **HTTP 方法**：GET
- **路径**：`/api/oauth/telegram/bind`
- **鉴权要求**：公开
- **功能简介**：将 Telegram 账户绑定到现有用户账户

#### 💡 请求示例：

```javascript
// 通过TelegramLoginButton组件自动处理参数  
// 参数格式与Telegram登录相同  
const response = await fetch('/api/oauth/telegram/bind', {  
  method: 'GET',  
  params: telegram_auth_params  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "Telegram账户绑定成功！"  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "该Telegram账户已被绑定"  
}
```

#### 🧾 字段说明：

- 参数格式与 Telegram 登录接口相同

### 获取随机 state（防 CSRF）

- **接口名称**：获取随机 state
- **HTTP 方法**：GET
- **路径**：`/api/oauth/state`
- **鉴权要求**：公开
- **功能简介**：生成随机 state 参数用于 OAuth 流程的 CSRF 防护

#### 💡 请求示例：

```javascript
let path = '/api/oauth/state';  
let affCode = localStorage.getItem('aff');  
if (affCode && affCode.length > 0) {  
  path += `?aff=${affCode}`;  
}  
const response = await fetch(path, {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": "random_state_string_12chars"  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "生成state失败"  
}
```

#### 🧾 字段说明：

- **aff** （字符串）: 可选，推荐码参数，用于记录用户来源
- **data** （字符串）: 返回的随机 state 字符串，长度为 12 位

# 用户模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

核心用户管理系统，实现四级权限体系（公开/用户/管理员/Root）和完整的用户生命周期管理。包含注册登录、个人资料、Token 管理、充值支付、推广系统等功能。支持 2FA、邮箱验证和多种 OAuth 登录方式。

## 账号注册/登录

### 🔐 无需鉴权

#### 注册新账号

- **接口名称**：注册新账号
- **HTTP 方法**：POST
- **路径**：`/api/user/register`
- **鉴权要求**：公开
- **功能简介**：创建新用户账户，支持邮箱验证和推荐码功能

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/register', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json'  
  },  
  body: JSON.stringify({  
    username: "newuser",  
    password: "password123",  
    email: "user@example.com",  
    verification_code: "123456",  
    aff_code: "INVITE123"  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "用户注册成功"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "管理员关闭了新用户注册"  
}
```

##### 🧾 字段说明：

- **username** （字符串）: 用户名，必填
- **password** （字符串）: 密码，必填
- **email** （字符串）: 邮箱地址，当启用邮箱验证时必填
- **verification_code** （字符串）: 邮箱验证码，当启用邮箱验证时必填
- **aff_code** （字符串）: 推荐码，可选

#### 用户登录

- **接口名称**：用户登录
- **HTTP 方法**：POST
- **路径**：`/api/user/login`
- **鉴权要求**：公开
- **功能简介**：用户账户登录，支持两步验证（2FA）

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/login', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json'  
  },  
  body: JSON.stringify({  
    username: "testuser",  
    password: "password123"  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例（无 2FA）：

```json
{  
  "success": true,  
  "message": "登录成功",  
  "data": {  
    "token": "user_access_token",  
    "user": {  
      "id": 1,  
      "username": "testuser",  
      "role": 1,  
      "quota": 1000000  
    }  
  }  
}
```

##### ✅ 成功响应示例（需要 2FA）：

```json
{  
  "success": true,  
  "message": "请输入两步验证码",  
  "data": {  
    "require_2fa": true  
  }  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "管理员关闭了密码登录"  
}
```

##### 🧾 字段说明：

- **username** （字符串）: 用户名，必填
- **password** （字符串）: 密码，必填
- **require_2fa** （布尔型）: 是否需要两步验证

#### Epay 支付回调

- **接口名称**：Epay 支付回调
- **HTTP 方法**：GET
- **路径**：`/api/user/epay/notify`
- **鉴权要求**：公开
- **功能简介**：处理易支付系统的支付回调通知

##### 💡 请求示例：

```
// 通常由支付系统自动回调，前端无需主动调用  
// 示例URL: /api/user/epay/notify?trade_no=USR1NO123456&money=10.00&trade_status=TRADE_SUCCESS
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "支付成功"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "订单不存在或已处理"  
}
```

##### 🧾 字段说明：

- **trade_no** （字符串）: 交易订单号
- **money** （字符串）: 支付金额
- **trade_status** （字符串）: 交易状态
- **sign** （字符串）: 签名验证

#### 列出所有分组（无鉴权版）

- **接口名称**：列出所有分组
- **HTTP 方法**：GET
- **路径**：`/api/user/groups`
- **鉴权要求**：公开
- **功能简介**：获取系统中所有用户分组信息，无需登录即可访问

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/groups', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "default": {  
      "ratio": 1.0,  
      "desc": "默认分组"  
    },  
    "vip": {  
      "ratio": 0.8,  
      "desc": "VIP分组"  
    },  
    "auto": {  
      "ratio": "自动",  
      "desc": "自动选择最优分组"  
    }  
  }  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取分组信息失败"  
}
```

##### 🧾 字段说明：

- **data** （对象）: 分组信息映射
  - **键** （字符串）: 分组名称
  - **ratio** （数字/字符串）: 分组倍率，"自动"表示自动选择
  - **desc** （字符串）: 分组描述

### 🔐 用户鉴权

#### 退出登录

- **接口名称**：退出登录
- **HTTP 方法**：GET
- **路径**：`/api/user/logout`
- **鉴权要求**：用户
- **功能简介**：清除用户会话，退出登录状态

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/logout', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "会话清除失败"  
}
```

##### 🧾 字段说明：

- 无请求参数

## 用户自身操作

### 🔐 用户鉴权

#### 获取自己所在分组

- **接口名称**：获取自己所在分组
- **HTTP 方法**：GET
- **路径**：`/api/user/self/groups`
- **鉴权要求**：用户
- **功能简介**：获取当前登录用户可使用的分组信息，包含分组倍率和描述

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/self/groups', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "default": {  
      "ratio": 1.0,  
      "desc": "默认分组"  
    },  
    "vip": {  
      "ratio": 0.8,  
      "desc": "VIP分组"  
    },  
    "auto": {  
      "ratio": "自动",  
      "desc": "自动选择最优分组"  
    }  
  }  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取分组信息失败"  
}
```

##### 🧾 字段说明：

- **data** （对象）: 用户可用分组信息映射 group.go：25-48
  - **键** （字符串）: 分组名称
  - **ratio** （数字/字符串）: 分组倍率，"自动"表示自动选择最优分组
  - **desc** （字符串）: 分组描述

#### 获取个人资料

- **接口名称**：获取个人资料
- **HTTP 方法**：GET
- **路径**：`/api/user/self`
- **鉴权要求**：用户
- **功能简介**：获取当前用户的详细信息，包含权限、配额、设置等

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/self', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "id": 1,  
    "username": "testuser",  
    "display_name": "Test User",  
    "role": 1,  
    "status": 1,  
    "email": "user@example.com",  
    "group": "default",  
    "quota": 1000000,  
    "used_quota": 50000,  
    "request_count": 100,  
    "aff_code": "ABC123",  
    "aff_count": 5,  
    "aff_quota": 10000,  
    "aff_history_quota": 50000,  
    "inviter_id": 0,  
    "linux_do_id": "",  
    "setting": "{}",  
    "stripe_customer": "",  
    "sidebar_modules": "{\"chat\":{\"enabled\":true}}",  
    "permissions": {  
      "can_view_logs": true,  
      "can_manage_tokens": true  
    }  
  }  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取用户信息失败"  
}
```

##### 🧾 字段说明：

- **id** （数字）: 用户 ID
- **username** （字符串）: 用户名
- **display_name** （字符串）: 显示名称
- **role** （数字）: 用户角色，1=普通用户，10=管理员，100=Root 用户
- **status** （数字）: 用户状态，1=正常，2=禁用
- **email** （字符串）: 邮箱地址
- **group** （字符串）: 所属分组
- **quota** （数字）: 总配额
- **used_quota** （数字）: 已使用配额
- **request_count** （数字）: 请求次数
- **aff_code** （字符串）: 推荐码
- **aff_count** （数字）: 推荐人数
- **aff_quota** （数字）: 推荐奖励配额
- **aff_history_quota** （数字）: 历史推荐配额
- **inviter_id** （数字）: 邀请人 ID
- **linux_do_id** （字符串）: LinuxDo 账户 ID
- **setting** （字符串）: 用户设置 JSON 字符串
- **stripe_customer** （字符串）: Stripe 客户 ID
- **sidebar_modules** （字符串）: 侧边栏模块配置 JSON 字符串
- **permissions** （对象）: 用户权限信息

#### 获取模型可见性

- **接口名称**：获取模型可见性
- **HTTP 方法**：GET
- **路径**：`/api/user/models`
- **鉴权要求**：用户
- **功能简介**：获取当前用户可访问的 AI 模型列表

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/models', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": [  
    "gpt-3.5-turbo",  
    "gpt-4",  
    "claude-3-sonnet",  
    "claude-3-haiku"  
  ]  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取模型列表失败"  
}
```

##### 🧾 字段说明：

- **data** （数组）: 用户可访问的模型名称列表

#### 修改个人资料

- **接口名称**：修改个人资料
- **HTTP 方法**：PUT
- **路径**：`/api/user/self`
- **鉴权要求**：用户
- **功能简介**：更新用户个人信息或侧边栏设置

##### 💡 请求示例（更新个人信息）：

```javascript
const response = await fetch('/api/user/self', {  
  method: 'PUT',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    display_name: "New Display Name",  
    email: "newemail@example.com"  
  })  
});  
const data = await response.json();
```

##### 💡 请求示例（更新侧边栏设置）：

```javascript
const response = await fetch('/api/user/self', {  
  method: 'PUT',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    sidebar_modules: JSON.stringify({  
      chat: { enabled: true, playground: true },  
      console: { enabled: true, token: true }  
    })  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "更新成功"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "输入不合法"  
}
```

##### 🧾 字段说明：

- **display_name** （字符串）: 显示名称，可选
- **email** （字符串）: 邮箱地址，可选
- **password** （字符串）: 新密码，可选
- **sidebar_modules** （字符串）: 侧边栏模块配置 JSON 字符串，可选

#### 注销账号

- **接口名称**：注销账号
- **HTTP 方法**：DELETE
- **路径**：`/api/user/self`
- **鉴权要求**：用户
- **功能简介**：删除当前用户账户，Root 用户不可删除

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/self', {  
  method: 'DELETE',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "不能删除超级管理员账户"  
}
```

##### 🧾 字段说明：

- 无请求参数

#### 生成用户级别 Access Token

- **接口名称**：生成用户级别 Access Token
- **HTTP 方法**：GET
- **路径**：`/api/user/token`
- **鉴权要求**：用户
- **功能简介**：为当前用户生成新的访问令牌，用于 API 调用

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/token', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": "<YOUR_API_KEY>"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "生成令牌失败"  
}
```

##### 🧾 字段说明：

- **data** （字符串）: 生成的访问令牌

#### 获取推广码信息

- **接口名称**：获取推广码信息
- **HTTP 方法**：GET
- **路径**：`/api/user/aff`
- **鉴权要求**：用户
- **功能简介**：获取或生成用户的推广码，用于邀请新用户注册

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/aff', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": "ABC123"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取推广码失败"  
}
```

##### 🧾 字段说明：

- **data** （字符串）: 用户的推广码，如果不存在会自动生成 4 位随机字符串

#### 余额直充

- **接口名称**：余额直充
- **HTTP 方法**：POST
- **路径**：`/api/user/topup`
- **鉴权要求**：用户
- **功能简介**：使用兑换码为账户充值配额

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/topup', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    key: "REDEEM123456"  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "兑换成功",  
  "data": 100000  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "兑换码无效或已使用"  
}
```

##### 🧾 字段说明：

- **key** （字符串）: 兑换码，必填
- **data** （数字）: 成功时返回兑换的配额数量

#### 提交支付订单

- **接口名称**：提交支付订单
- **HTTP 方法**：POST
- **路径**：`/api/user/pay`
- **鉴权要求**：用户
- **功能简介**：创建在线支付订单，支持多种支付方式

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/pay', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    amount: 10000,  
    payment_method: "alipay",  
    top_up_code: ""  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "success",  
  "data": {  
    "pid": "12345",  
    "type": "alipay",  
    "out_trade_no": "USR1NO123456",  
    "notify_url": "https://example.com/notify",  
    "return_url": "https://example.com/return",  
    "name": "TUC10000",  
    "money": "10.00",  
    "sign": "abc123def456"  
  },  
  "url": "https://pay.example.com/submit"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "充值数量不能小于 1000"  
}
```

##### 🧾 字段说明：

- **amount** （数字）: 充值数量，必须大于等于最小充值额度 topup.go：133-136
- **payment_method** （字符串）: 支付方式，如"alipay"、"wxpay"等
- **top_up_code** （字符串）: 充值码，可选
- **data** （对象）: 支付表单参数
- **url** （字符串）: 支付提交地址

#### 余额支付

- **接口名称**：余额支付
- **HTTP 方法**：POST
- **路径**：`/api/user/amount`
- **鉴权要求**：用户
- **功能简介**：计算指定充值数量对应的实际支付金额

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/amount', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    amount: 10000,  
    top_up_code: ""  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "success",  
  "data": "10.00"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "充值数量不能小于 1000"  
}
```

##### 🧾 字段说明：

- **amount** （数字）: 充值数量，必须大于等于最小充值额度
- **top_up_code** （字符串）: 充值码，可选
- **data** （字符串）: 实际需要支付的金额（元）

#### 推广额度转账

- **接口名称**：推广额度转账
- **HTTP 方法**：POST
- **路径**：`/api/user/aff_transfer`
- **鉴权要求**：用户
- **功能简介**：将推广奖励额度转换为可用配额

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/aff_transfer', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    quota: 50000  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "划转成功"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "邀请额度不足！"  
}
```

##### 🧾 字段说明：

- **quota** （数字）: 要转换的额度数量，必须大于等于最小单位额度

#### 更新用户设置

- **接口名称**：更新用户设置
- **HTTP 方法**：PUT
- **路径**：`/api/user/setting`
- **鉴权要求**：用户
- **功能简介**：更新用户的个人设置配置

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/setting', {  
  method: 'PUT',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    theme: "dark",  
    language: "zh-CN",  
    notifications: {  
      email: true,  
      browser: false  
    }  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "设置更新成功"  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "设置格式错误"  
}
```

##### 🧾 字段说明：

- 请求体可包含任意用户设置字段，以 JSON 格式提交
- 具体字段根据前端设置页面的需求而定

## 管理员用户管理

### 🔐 管理员鉴权

#### 获取全部用户列表

- **接口名称**：获取全部用户列表
- **HTTP 方法**：GET
- **路径**：`/api/user/`
- **鉴权要求**：管理员
- **功能简介**：分页获取系统中所有用户的列表信息

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/?p=1&page_size=20', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "username": "testuser",  
        "display_name": "Test User",  
        "role": 1,  
        "status": 1,  
        "email": "user@example.com",  
        "group": "default",  
        "quota": 1000000,  
        "used_quota": 50000,  
        "request_count": 100  
      }  
    ],  
    "total": 50,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取用户列表失败"  
}
```

##### 🧾 字段说明：

- **p** （数字）: 页码，默认为 1
- **page_size** （数字）: 每页数量，默认为 20
- **items** （数组）: 用户信息列表
- **total** （数字）: 用户总数
- **page** （数字）: 当前页码
- **page_size** （数字）: 每页数量

#### 搜索用户

- **接口名称**：搜索用户
- **HTTP 方法**：GET
- **路径**：`/api/user/search`
- **鉴权要求**：管理员
- **功能简介**：根据关键词和分组搜索用户

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/search?keyword=test&group=default&p=1&page_size=20', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "username": "testuser",  
        "display_name": "Test User",  
        "role": 1,  
        "status": 1,  
        "email": "test@example.com",  
        "group": "default"  
      }  
    ],  
    "total": 1,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "搜索用户失败"  
}
```

##### 🧾 字段说明：

- **keyword** （字符串）: 搜索关键词，可匹配用户名、显示名、邮箱
- **group** （字符串）: 用户分组过滤条件
- **p** （数字）: 页码，默认为 1
- **page_size** （数字）: 每页数量，默认为 20

#### 获取单个用户信息

- **接口名称**：获取单个用户信息
- **HTTP 方法**：GET
- **路径**：`/api/user/:id`
- **鉴权要求**：管理员
- **功能简介**：获取指定用户的详细信息，包含权限检查

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/123', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "id": 123,  
    "username": "targetuser",  
    "display_name": "Target User",  
    "role": 1,  
    "status": 1,  
    "email": "target@example.com",  
    "group": "default",  
    "quota": 1000000,  
    "used_quota": 50000,  
    "request_count": 100,  
    "aff_code": "ABC123",  
    "aff_count": 5  
  }  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "无权获取同级或更高等级用户的信息"  
}
```

##### 🧾 字段说明：

- **id** （数字）: 用户 ID，通过 URL 路径传递
- 返回完整的用户信息，但管理员无法查看同级或更高权限用户的信息

#### 创建用户

- **接口名称**：创建用户
- **HTTP 方法**：POST
- **路径**：`/api/user/`
- **鉴权要求**：管理员
- **功能简介**：创建新用户账户，管理员不能创建权限大于等于自己的用户

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id' 
  },  
  body: JSON.stringify({  
    username: "newuser",  
    password: "password123",  
    display_name: "New User",  
    role: 1  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "无法创建权限大于等于自己的用户"  
}
```

##### 🧾 字段说明：

- **username** （字符串）: 用户名，必填
- **password** （字符串）: 密码，必填
- **display_name** （字符串）: 显示名称，可选，默认为用户名
- **role** （数字）: 用户角色，必须小于当前管理员角色

#### 冻结/重置等管理操作

- **接口名称**：冻结/重置等管理操作
- **HTTP 方法**：POST
- **路径**：`/api/user/manage`
- **鉴权要求**：管理员
- **功能简介**：对用户执行管理操作，包括启用、禁用、删除、提升、降级等

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/manage', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    id: 123,  
    action: "disable"  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "无法禁用超级管理员用户"  
}
```

##### 🧾 字段说明：

- **id** （数字）: 目标用户 ID，必填
- **action** （字符串）: 操作类型，必填，可选值：
  - **disable**： 禁用用户
  - **enable**： 启用用户
  - **delete**： 删除用户
  - **promote**： 提升为管理员（仅 Root 用户可操作）
  - **demote**： 降级为普通用户

#### 更新用户

- **接口名称**：更新用户
- **HTTP 方法**：PUT
- **路径**：`/api/user/`
- **鉴权要求**：管理员
- **功能简介**：更新用户信息，包含权限检查和配额变更记录

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/', {  
  method: 'PUT',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    id: 123,  
    username: "updateduser",  
    display_name: "Updated User",  
    email: "updated@example.com",  
    quota: 2000000,  
    role: 1,  
    status: 1  
  })  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "无权更新同权限等级或更高权限等级的用户信息"  
}
```

##### 🧾 字段说明：

- **id** （数字）: 用户 ID，必填
- **username** （字符串）: 用户名，可选
- **display_name** （字符串）: 显示名称，可选
- **email** （字符串）: 邮箱地址，可选
- **password** （字符串）: 新密码，可选，为空则不更新密码
- **quota** （数字）: 用户配额，可选
- **role** （数字）: 用户角色，不能大于等于当前管理员角色
- **status** （数字）: 用户状态，可选

#### 删除用户

- **接口名称**：删除用户
- **HTTP 方法**：DELETE
- **路径**：`/api/user/:id`
- **鉴权要求**：管理员
- **功能简介**：硬删除指定用户，管理员不能删除同级或更高权限用户

##### 💡 请求示例：

```javascript
const response = await fetch('/api/user/123', {  
  method: 'DELETE',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

##### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

##### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "无权删除同权限等级或更高权限等级的用户"  
}
```

##### 🧾 字段说明：

- **id** （数字）: 用户 ID，通过 URL 路径传递
- 执行硬删除操作，不可恢复

# Token 管理模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

用户 API Token 的完整管理系统。支持 Token 创建、更新、删除、批量操作等功能。包含模型限制、IP 限制、配额管理、过期时间等精细化控制。前端 Token 页面的核心数据来源。

## 🔐 用户鉴权

### 获取全部 Token

- **接口名称**：获取全部 Token
- **HTTP 方法**：GET
- **路径**：`/api/token/`
- **鉴权要求**：用户
- **功能简介**：分页获取当前用户的所有 Token 列表

#### 💡 请求示例：

```javascript
const response = await fetch('/api/token/?p=1&size=20', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "name": "API Token",  
        "key": "<YOUR_API_KEY>",  
        "status": 1,  
        "remain_quota": 1000000,  
        "unlimited_quota": false,  
        "expired_time": 1640995200,  
        "created_time": 1640908800,  
        "accessed_time": 1640995000  
      }  
    ],  
    "total": 5,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取Token列表失败"  
}
```

#### 🧾 字段说明：

- **p** （数字）: 页码，默认为 1
- **size** （数字）: 每页数量，默认为 20
- **items** （数组）: Token 信息列表
- **total** （数字）: Token 总数
- **page** （数字）: 当前页码
- **page_size** （数字）: 每页数量

### 搜索 Token

- **接口名称**：搜索 Token
- **HTTP 方法**：GET
- **路径**：`/api/token/search`
- **鉴权要求**：用户
- **功能简介**：根据关键词和 Token 值搜索用户的 Token

#### 💡 请求示例：

```javascript
const response = await fetch('/api/token/search?keyword=api&token=sk-123', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": [  
    {  
      "id": 1,  
      "name": "API Token",  
      "key": "sk-your-token-placeholder",  
      "status": 1,  
      "remain_quota": 1000000  
    }  
  ]  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "搜索Token失败"  
}
```

#### 🧾 字段说明：

- **keyword** （字符串）: 搜索关键词，匹配 Token 名称
- **token** （字符串）: Token 值搜索，支持部分匹配

### 获取单个 Token

- **接口名称**：获取单个 Token
- **HTTP 方法**：GET
- **路径**：`/api/token/:id`
- **鉴权要求**：用户
- **功能简介**：获取指定 Token 的详细信息

#### 💡 请求示例：

```javascript
const response = await fetch('/api/token/123', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "id": 123,  
    "name": "API Token",  
    "key": "sk-your-token-placeholder",  
    "status": 1,  
    "remain_quota": 1000000,  
    "unlimited_quota": false,  
    "model_limits_enabled": true,  
    "model_limits": "gpt-3.5-turbo,gpt-4",  
    "allow_ips": "192.168.1.1,10.0.0.1",  
    "group": "default",  
    "expired_time": 1640995200,  
    "created_time": 1640908800,  
    "accessed_time": 1640995000  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "Token不存在"  
}
```

#### 🧾 字段说明：

- **id** （数字）: Token ID，通过 URL 路径传递

### 创建 Token

- **接口名称**：创建 Token
- **HTTP 方法**：POST
- **路径**：`/api/token/`
- **鉴权要求**：用户
- **功能简介**：创建新的 API Token，支持批量创建

#### 💡 请求示例：

```javascript
const response = await fetch('/api/token/', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    name: "My API Token",  
    expired_time: 1640995200,  
    remain_quota: 1000000,  
    unlimited_quota: false,  
    model_limits_enabled: true,  
    model_limits: ["gpt-3.5-turbo", "gpt-4"],  
    allow_ips: "192.168.1.1,10.0.0.1",  
    group: "default"  
  })  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "令牌名称过长"  
}
```

#### 🧾 字段说明：

- **name** （字符串）: Token 名称，最大长度 30 个字符
- **expired_time** （数字）: 过期时间戳，-1 表示永不过期
- **remain_quota** （数字）: 剩余配额
- **unlimited_quota** （布尔型）: 是否无限配额
- **model_limits_enabled** （布尔型）: 是否启用模型限制
- **model_limits** （数组）: 允许使用的模型列表
- **allow_ips** （字符串）: 允许的 IP 地址，逗号分隔
- **group** （字符串）: 所属分组

### 更新 Token

- **接口名称**：更新 Token
- **HTTP 方法**：PUT
- **路径**：`/api/token/`
- **鉴权要求**：用户
- **功能简介**：更新 Token 配置，支持状态切换和完整更新

#### 💡 请求示例（完整更新）：

```javascript
const response = await fetch('/api/token/', {  
  method: 'PUT',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id' 
  },  
  body: JSON.stringify({  
    id: 123,  
    name: "Updated Token",  
    expired_time: 1640995200,  
    remain_quota: 2000000,  
    unlimited_quota: false,  
    model_limits_enabled: true,  
    model_limits: ["gpt-3.5-turbo", "gpt-4"],  
    allow_ips: "192.168.1.1",  
    group: "vip"  
  })  
});  
const data = await response.json();
```

#### 💡 请求示例（仅更新状态）：

```javascript
const response = await fetch('/api/token/?status_only=true', {  
  method: 'PUT',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    id: 123,  
    status: 1  
  })  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "id": 123,  
    "name": "Updated Token",  
    "status": 1  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "令牌已过期，无法启用，请先修改令牌过期时间，或者设置为永不过期"  
}
```

#### 🧾 字段说明：

- **id** （数字）: Token ID，必填
- **status_only** （查询参数）: 是否仅更新状态
- 其他字段与创建 Token 接口相同，均为可选

### 删除 Token

- **接口名称**：删除 Token
- **HTTP 方法**：DELETE
- **路径**：`/api/token/:id`
- **鉴权要求**：用户
- **功能简介**：删除指定的 Token

#### 💡 请求示例：

```javascript
const response = await fetch('/api/token/123', {  
  method: 'DELETE',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id' 
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": ""  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "Token不存在"  
}
```

#### 🧾 字段说明：

- **id** （数字）: Token ID，通过 URL 路径传递

### 批量删除 Token

- **接口名称**：批量删除 Token
- **HTTP 方法**：POST
- **路径**：`/api/token/batch`
- **鉴权要求**：用户
- **功能简介**：批量删除多个 Token

#### 💡 请求示例：

```javascript
const response = await fetch('/api/token/batch', {  
  method: 'POST',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  },  
  body: JSON.stringify({  
    ids: [1, 2, 3, 4, 5]  
  })  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": 5  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "参数错误"  
}
```

#### 🧾 字段说明：

- **ids** （数组）: 要删除的 Token ID 列表，必填且不能为空
- **data** （数字）: 成功删除的 Token 数量

# 令牌用量查询（Token Usage）API 文档

## 功能说明

通过认证查询当前 Bearer Token 的额度使用情况：授予总量、已用、剩余、是否无限、模型限额及到期时间。

## 📮 端点

```
GET /api/usage/token
```

- 需要在请求头中携带鉴权信息
- 仅返回当前请求所使用的 Token 的用量信息

## 🔐 鉴权

在请求头中包含以下内容进行 API 密钥认证：

```
Authorization: Bearer $NEWAPI_API_KEY
```

- 支持携带或不携带 `sk-` 前缀，服务端会自动兼容
- 缺少或无效的 Authorization 头将返回 401

## 💡 请求示例

```bash
curl -X GET https://ai.burncloud.com/api/usage/token \
  -H "Authorization: Bearer $NEWAPI_API_KEY"
```

## ✅ 成功响应示例

```json
{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "Default Token",
    "total_granted": 1000000,
    "total_used": 12345,
    "total_available": 987655,
    "unlimited_quota": false,
    "model_limits": {
      "gpt-4o-mini": true
    },
    "model_limits_enabled": false,
    "expires_at": 0
  }
}
```

## ❗ 错误响应示例

### 缺少鉴权头：

```json
{
  "success": false,
  "message": "No Authorization header"
}
```

### 非 Bearer 方案：

```json
{
  "success": false,
  "message": "Invalid Bearer token"
}
```

### Token 查找失败（例如无效或已删除）：

```json
{
  "success": false,
  "message": "token not found"
}
```

## 🧾 字段说明（data）

| 字段 | 描述 |
|------|------|
| object | 固定为 `token_usage` |
| name | 令牌名称 |
| total_granted | 授予总量（= 已用 + 剩余） |
| total_used | 已使用额度 |
| total_available | 可用剩余额度 |
| unlimited_quota | 是否为无限额度 |
| model_limits | 允许使用的模型列表 |
| model_limits_enabled | 是否启用模型限额 |
| expires_at | 到期时间的 Unix 时间戳（秒）。若永不过期返回 0（由后端将 -1 归一化为 0） |

# 日志模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

分层的日志查询系统，支持管理员查看全站日志和用户查看个人日志。提供实时统计（RPM/TPM）、多维度过滤、历史数据清理等功能。支持 CORS 的 Token 查询接口便于第三方集成。

## 🔐 无需鉴权

### 根据 Token 查询日志

- **接口名称**：根据 Token 查询日志
- **HTTP 方法**：GET
- **路径**：`/api/log/token`
- **鉴权要求**：公开
- **功能简介**：通过 Token 密钥查询相关日志记录，支持跨域访问

#### 💡 请求示例：

```javascript
const response = await fetch('/api/log/token?key=<TOKEN_PLACEHOLDER>', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json'  
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": [  
    {  
      "id": 1,  
      "type": 2,  
      "content": "API调用成功",  
      "model_name": "gpt-4",  
      "quota": 1000,  
      "created_at": 1640995000  
    }  
  ]  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "Token不存在或无权限"  
}
```

#### 🧾 字段说明：

- **key** （字符串）: Token 密钥，必填

## 🔐 用户鉴权

### 我的日志统计

- **接口名称**：我的日志统计
- **HTTP 方法**：GET
- **路径**：`/api/log/self/stat`
- **鉴权要求**：用户
- **功能简介**：获取当前用户的日志统计信息，包括配额消耗、请求频率和 Token 使用量

#### 💡 请求示例：

```javascript
const response = await fetch('/api/log/self/stat?type=2&start_timestamp=1640908800&end_timestamp=1640995200&token_name=api_token&model_name=gpt-4&group=default', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "quota": 50000,  
    "rpm": 10,  
    "tpm": 1500  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取统计信息失败"  
}
```

#### 🧾 字段说明：

- **type** （数字）: 日志类型，可选值：1=充值，2=消费，3=管理，4=错误，5=系统
- **start_timestamp** （数字）: 开始时间戳
- **end_timestamp** （数字）: 结束时间戳
- **token_name** （字符串）: Token 名称过滤
- **model_name** （字符串）: 模型名称过滤
- **group** （字符串）: 分组过滤
- **quota** （数字）: 指定时间范围内的总配额消耗
- **rpm** （数字）: 每分钟请求数（最近 60 秒）
- **tpm** （数字）: 每分钟 Token 数（最近 60 秒）

### 获取我的日志

- **接口名称**：获取我的日志
- **HTTP 方法**：GET
- **路径**：`/api/log/self`
- **鉴权要求**：用户
- **功能简介**：分页获取当前用户的日志记录，支持多种过滤条件

#### 💡 请求示例：

```javascript
const response = await fetch('/api/log/self?p=1&page_size=20&type=2&start_timestamp=1640908800&end_timestamp=1640995200&token_name=api_token&model_name=gpt-4&group=default', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "user_id": 1,  
        "created_at": 1640995000,  
        "type": 2,  
        "content": "API调用成功",  
        "token_name": "api_token",  
        "model_name": "gpt-4",  
        "quota": 1000,  
        "prompt_tokens": 50,  
        "completion_tokens": 100  
      }  
    ],  
    "total": 25,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取日志失败"  
}
```

#### 🧾 字段说明：

请求参数与获取全部日志接口相同，但只返回当前用户的日志记录

### 搜索我的日志

- **接口名称**：搜索我的日志
- **HTTP 方法**：GET
- **路径**：`/api/log/self/search`
- **鉴权要求**：用户
- **功能简介**：根据关键词搜索当前用户的日志记录

#### 💡 请求示例：

```javascript
const response = await fetch('/api/log/self/search?keyword=gpt-4', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": [  
    {  
      "id": 1,  
      "type": 2,  
      "content": "GPT-4调用成功",  
      "model_name": "gpt-4",  
      "created_at": 1640995000  
    }  
  ]  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "搜索日志失败"  
}
```

#### 🧾 字段说明：

- **keyword** （字符串）: 搜索关键词，匹配当前用户的日志类型

## 🔐 管理员鉴权

### 获取全部日志

- **接口名称**：获取全部日志
- **HTTP 方法**：GET
- **路径**：`/api/log/`
- **鉴权要求**：管理员
- **功能简介**：分页获取系统中所有日志记录，支持多种过滤条件和日志类型筛选

#### 💡 请求示例：

```javascript
const response = await fetch('/api/log/?p=1&page_size=20&type=2&start_timestamp=1640908800&end_timestamp=1640995200&username=testuser&token_name=api_token&model_name=gpt-4&channel=1&group=default', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "user_id": 1,  
        "created_at": 1640995000,  
        "type": 2,  
        "content": "API调用成功",  
        "username": "testuser",  
        "token_name": "api_token",  
        "model_name": "gpt-4",  
        "quota": 1000,  
        "prompt_tokens": 50,  
        "completion_tokens": 100,  
        "use_time": 2,  
        "is_stream": false,  
        "channel_id": 1,  
        "channel_name": "OpenAI渠道",  
        "token_id": 1,  
        "group": "default",  
        "ip": "192.168.1.1",  
        "other": "{\"model_ratio\":15.0}"  
      }  
    ],  
    "total": 100,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取日志失败"  
}
```

#### 🧾 字段说明：

- **p** （数字）: 页码，默认为 1
- **page_size** （数字）: 每页数量，默认为 20
- **type** （数字）: 日志类型，可选值：1=充值，2=消费，3=管理，4=错误，5=系统
- **start_timestamp** （数字）: 开始时间戳
- **end_timestamp** （数字）: 结束时间戳
- **username** （字符串）: 用户名过滤
- **token_name** （字符串）: Token 名称过滤
- **model_name** （字符串）: 模型名称过滤
- **channel** （数字）: 渠道 ID 过滤
- **group** （字符串）: 分组过滤

### 删除历史日志

- **接口名称**：删除历史日志
- **HTTP 方法**：DELETE
- **路径**：`/api/log/`
- **鉴权要求**：管理员
- **功能简介**：批量删除指定时间戳之前的历史日志记录，支持分批删除以避免数据库负载过高

#### 💡 请求示例：

```javascript
const response = await fetch('/api/log/?target_timestamp=1640908800', {  
  method: 'DELETE',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": 1500  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "target timestamp is required"  
}
```

#### 🧾 字段说明：

- **target_timestamp** （数字）: 目标时间戳，删除此时间之前的所有日志，必填
- **data** （数字）: 成功删除的日志条数

### 日志统计

- **接口名称**：日志统计
- **HTTP 方法**：GET
- **路径**：`/api/log/stat`
- **鉴权要求**：管理员
- **功能简介**：获取指定时间范围和条件下的日志统计信息，包括配额消耗、请求频率和 Token 使用量

#### 💡 请求示例：

```javascript
const response = await fetch('/api/log/stat?type=2&start_timestamp=1640908800&end_timestamp=1640995200&username=testuser&token_name=api_token&model_name=gpt-4&channel=1&group=default', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id' 
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "quota": 150000,  
    "rpm": 25,  
    "tpm": 3500  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取统计信息失败"  
}
```

#### 🧾 字段说明：

请求参数与获取全部日志接口相同
- **quota** （数字）: 指定时间范围内的总配额消耗
- **rpm** （数字）: 每分钟请求数（最近 60 秒）
- **tpm** （数字）: 每分钟 Token 数（最近 60 秒的 prompt_tokens + completion_tokens 总和）

### 搜索全部日志

- **接口名称**：搜索全部日志
- **HTTP 方法**：GET
- **路径**：`/api/log/search`
- **鉴权要求**：管理员
- **功能简介**：根据关键词搜索系统中所有日志记录

#### 💡 请求示例：

```javascript
const response = await fetch('/api/log/search?keyword=error', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": [  
    {  
      "id": 1,  
      "type": 4,  
      "content": "API调用错误",  
      "username": "testuser",  
      "created_at": 1640995000  
    }  
  ]  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "搜索日志失败"  
}
```

#### 🧾 字段说明：

- **keyword** （字符串）: 搜索关键词，可匹配日志类型或内容

# 数据统计模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

用量数据的聚合统计系统。管理员可查看全站统计，用户可查看个人统计。数据按模型和日期分组，用于生成图表和报表，监控系统使用趋势。

## 🔐 用户鉴权

### 我的用量按日期统计

- **接口名称**：我的用量按日期统计
- **HTTP 方法**：GET
- **路径**：`/api/data/self`
- **鉴权要求**：用户
- **功能简介**：获取当前用户的用量数据按日期统计，支持时间范围查询

#### 💡 请求示例：

```javascript
const response = await fetch('/api/data/self?start_timestamp=1640908800&end_timestamp=1640995200', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": [  
    {  
      "model_name": "gpt-3.5-turbo",  
      "count": 25,  
      "quota": 12500,  
      "token_used": 2000,  
      "created_at": 1640995200,  
      "user_id": 1,  
      "username": "testuser"  
    },  
    {  
      "model_name": "gpt-4",  
      "count": 10,  
      "quota": 30000,  
      "token_used": 1500,  
      "created_at": 1640995200,  
      "user_id": 1,  
      "username": "testuser"  
    }  
  ]  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取个人统计数据失败"  
}
```

#### 🧾 字段说明：

- **start_timestamp** （数字）: 开始时间戳，可选
- **end_timestamp** （数字）: 结束时间戳，可选
- **data** （数组）: 个人统计数据列表
  - **model_name** （字符串）: 模型名称
  - **count** （数字）: 请求次数
  - **quota** （数字）: 配额消耗
  - **token_used** （数字）: Token 使用量
  - **created_at** （数字）: 统计日期时间戳
  - **user_id** （数字）: 用户 ID
  - **username** （字符串）: 用户名

## 🔐 管理员鉴权

### 全站用量按日期统计

- **接口名称**：全站用量按日期统计
- **HTTP 方法**：GET
- **路径**：`/api/data/`
- **鉴权要求**：管理员
- **功能简介**：获取系统全站用量数据按日期统计，支持按用户名过滤和时间范围查询

#### 💡 请求示例：

```javascript
const response = await fetch('/api/data/?start_timestamp=1640908800&end_timestamp=1640995200&username=testuser', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": [  
    {  
      "model_name": "gpt-3.5-turbo",  
      "count": 150,  
      "quota": 75000,  
      "token_used": 12500,  
      "created_at": 1640995200  
    },  
    {  
      "model_name": "gpt-4",  
      "count": 50,  
      "quota": 150000,  
      "token_used": 8000,  
      "created_at": 1640995200  
    }  
  ]  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取统计数据失败"  
}
```

#### 🧾 字段说明：

- **start_timestamp** （数字）: 开始时间戳，可选
- **end_timestamp** （数字）: 结束时间戳，可选
- **username** （字符串）: 用户名过滤，可选
- **data** （数组）: 统计数据列表，按模型和日期分组聚合
  - **model_name** （字符串）: 模型名称
  - **count** （数字）: 请求次数总和
  - **quota** （数字）: 配额消耗总和
  - **token_used** （数字）: Token 使用量总和
  - **created_at** （数字）: 统计日期时间戳

# Midjourney 任务模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

图像生成任务的管理系统。支持任务状态跟踪、进度监控、结果查看等功能。包含图片 URL 转发和后台轮询更新机制。

## 🔐 用户鉴权

### 获取自己的 MJ 任务

- **接口名称**：获取自己的 MJ 任务
- **HTTP 方法**：GET
- **路径**：`/api/mj/self`
- **鉴权要求**：用户
- **功能简介**：分页获取当前用户的 Midjourney 任务列表，支持按任务 ID 和时间范围过滤

#### 💡 请求示例：

```javascript
const response = await fetch('/api/mj/self?p=1&page_size=20&mj_id=task123&start_timestamp=1640908800&end_timestamp=1640995200', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "mj_id": "task123456",  
        "action": "IMAGINE",  
        "prompt": "a beautiful landscape",  
        "prompt_en": "a beautiful landscape",  
        "status": "SUCCESS",  
        "progress": "100%",  
        "image_url": "https://example.com/image.jpg",  
        "video_url": "https://example.com/video.mp4",  
        "video_urls": "[\"https://example.com/video1.mp4\"]",  
        "submit_time": 1640908800,  
        "start_time": 1640909000,  
        "finish_time": 1640909200,  
        "fail_reason": "",  
        "quota": 1000  
      }  
    ],  
    "total": 25,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取任务列表失败"  
}
```

#### 🧾 字段说明：

- **p** （数字）: 页码，默认为 1
- **page_size** （数字）: 每页数量，默认为 20
- **mj_id** （字符串）: 任务 ID 过滤，可选
- **start_timestamp** （数字）: 开始时间戳，可选
- **end_timestamp** （数字）: 结束时间戳，可选

返回字段说明：
- **id** （数字）: 数据库记录 ID
- **mj_id** （字符串）: Midjourney 任务唯一标识符
- **action** （字符串）: 操作类型，如 IMAGINE、UPSCALE 等
- **prompt** （字符串）: 原始提示词
- **prompt_en** （字符串）: 英文提示词
- **status** （字符串）: 任务状态 midjourney.go：19
- **progress** （字符串）: 完成进度百分比
- **image_url** （字符串）: 生成的图片 URL
- **video_url** （字符串）: 生成的视频 URL
- **video_urls** （字符串）: 多个视频 URL 的 JSON 数组字符串
- **submit_time** （数字）: 提交时间戳
- **start_time** （数字）: 开始处理时间戳
- **finish_time** （数字）: 完成时间戳
- **fail_reason** （字符串）: 失败原因
- **quota** （数字）: 消耗的配额

## 🔐 管理员鉴权

### 获取全部 MJ 任务

- **接口名称**：获取全部 MJ 任务
- **HTTP 方法**：GET
- **路径**：`/api/mj/`
- **鉴权要求**：管理员
- **功能简介**：分页获取系统中所有 Midjourney 任务，支持按渠道 ID、任务 ID 和时间范围过滤

#### 💡 请求示例：

```javascript
const response = await fetch('/api/mj/?p=1&page_size=20&channel_id=1&mj_id=task123&start_timestamp=1640908800&end_timestamp=1640995200', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "user_id": 1,  
        "mj_id": "task123456",  
        "action": "IMAGINE",  
        "prompt": "a beautiful landscape",  
        "status": "SUCCESS",  
        "progress": "100%",  
        "image_url": "https://example.com/image.jpg",  
        "channel_id": 1,  
        "quota": 1000,  
        "submit_time": 1640908800,  
        "finish_time": 1640909200  
      }  
    ],  
    "total": 100,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取任务列表失败"  
}
```

#### 🧾 字段说明：

- **p** （数字）: 页码，默认为 1
- **page_size** （数字）: 每页数量，默认为 20
- **channel_id** （字符串）: 渠道 ID 过滤，可选
- **mj_id** （字符串）: 任务 ID 过滤，可选
- **start_timestamp** （字符串）: 开始时间戳，可选
- **end_timestamp** （字符串）: 结束时间戳，可选

返回字段包含用户自身任务的所有字段，另外增加：
- **user_id** （数字）: 任务所属用户 ID
- **channel_id** （数字）: 使用的渠道 ID

# 任务中心模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

通用异步任务管理系统。主要支持 Suno 等平台的音乐生成任务。包含任务状态自动更新、失败重试、配额退还等机制。

## 🔐 用户鉴权

### 获取我的任务

- **接口名称**：获取我的任务
- **HTTP 方法**：GET
- **路径**：`/api/task/self`
- **鉴权要求**：用户
- **功能简介**：分页获取当前用户的任务列表，支持按平台、任务 ID、状态等条件过滤

#### 💡 请求示例：

```javascript
const response = await fetch('/api/task/self?p=1&page_size=20&platform=suno&task_id=task123&status=SUCCESS&action=song&start_timestamp=1640908800&end_timestamp=1640995200', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "created_at": 1640908800,  
        "updated_at": 1640909000,  
        "task_id": "task123456",  
        "platform": "suno",  
        "user_id": 1,  
        "quota": 1000,  
        "action": "song",  
        "status": "SUCCESS",  
        "fail_reason": "",  
        "submit_time": 1640908800,  
        "start_time": 1640908900,  
        "finish_time": 1640909000,  
        "progress": "100%",  
        "properties": {},  
        "data": {}  
      }  
    ],  
    "total": 25,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取任务列表失败"  
}
```

#### 🧾 字段说明：

- **p** （数字）: 页码，默认为 1
- **page_size** （数字）: 每页数量，默认为 20
- **platform** （字符串）: 任务平台，可选
- **task_id** （字符串）: 任务 ID 过滤，可选
- **status** （字符串）: 任务状态过滤，可选值："NOT_START"、"SUBMITTED"、"QUEUED"、"IN_PROGRESS"、"FAILURE"、"SUCCESS"、"UNKNOWN"
- **action** （字符串）: 任务类型过滤，如"song"、"lyrics"等
- **start_timestamp** （数字）: 开始时间戳，可选
- **end_timestamp** （数字）: 结束时间戳，可选

#### 🧾 返回字段说明：

- **id** （数字）: 数据库记录 ID
- **task_id** （字符串）: 第三方任务 ID
- **platform** （字符串）: 任务平台
- **user_id** （数字）: 用户 ID
- **quota** （数字）: 消耗的配额
- **action** （字符串）: 任务类型
- **status** （字符串）: 任务状态
- **fail_reason** （字符串）: 失败原因
- **submit_time** （数字）: 提交时间戳
- **start_time** （数字）: 开始时间戳
- **finish_time** （数字）: 完成时间戳
- **progress** （字符串）: 进度百分比
- **properties** （对象）: 任务属性
- **data** （对象）: 任务结果数据
- **total** （数字）: 符合条件的任务总记录数
- **page** （数字）: 当前返回的页码
- **page_size** （数字）: 每页展示的任务记录数

## 🔐 管理员鉴权

### 获取全部任务

- **接口名称**：获取全部任务
- **HTTP 方法**：GET
- **路径**：`/api/task/`
- **鉴权要求**：管理员
- **功能简介**：分页获取系统中所有任务，支持按渠道 ID、平台、用户 ID 等条件过滤

#### 💡 请求示例：

```javascript
const response = await fetch('/api/task/?p=1&page_size=20&channel_id=1&platform=suno&task_id=task123&status=SUCCESS&action=song&start_timestamp=1640908800&end_timestamp=1640995200', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "success": true,  
  "message": "",  
  "data": {  
    "items": [  
      {  
        "id": 1,  
        "created_at": 1640908800,  
        "task_id": "task123456",  
        "platform": "suno",  
        "user_id": 1,  
        "channel_id": 1,  
        "quota": 1000,  
        "action": "song",  
        "status": "SUCCESS",  
        "submit_time": 1640908800,  
        "finish_time": 1640909000,  
        "progress": "100%",  
        "data": {}  
      }  
    ],  
    "total": 100,  
    "page": 1,  
    "page_size": 20  
  }  
}
```

#### ❗ 失败响应示例：

```json
{  
  "success": false,  
  "message": "获取任务列表失败"  
}
```

#### 🧾 字段说明：

- **p** （数字）: 页码，默认为 1
- **page_size** （数字）: 每页数量，默认为 20
- **channel_id** （字符串）: 渠道 ID 过滤，可选
- **platform** （字符串）: 任务平台过滤，可选
- **task_id** （字符串）: 任务 ID 过滤，可选
- **status** （字符串）: 任务状态过滤，可选
- **action** （字符串）: 任务类型过滤，可选
- **start_timestamp** （数字）: 开始时间戳，可选
- **end_timestamp** （数字）: 结束时间戳，可选

返回字段包含用户任务的所有字段，另外增加：
- **channel_id** （数字）: 使用的渠道 ID

# 账户计费面板模块

## 功能说明

接口前缀为：
1. 主站：https://ai.burncloud.com
2. 企业站：https://b.burncloud.com

OpenAI SDK 兼容的计费查询接口。使用 Token 认证，提供订阅信息和使用量查询。主要用于第三方应用和 SDK 集成，确保与 OpenAI API 的完全兼容性。

## 🔐 用户鉴权

### 获取订阅额度信息

- **接口名称**：获取订阅额度信息
- **HTTP 方法**：GET
- **路径**：`/dashboard/billing/subscription`
- **鉴权要求**：用户 Token
- **功能简介**：获取用户的订阅配额信息，包括总额度、硬限制和访问有效期，兼容 OpenAI API 格式

#### 💡 请求示例：

```javascript
const response = await fetch('/dashboard/billing/subscription', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "object": "billing_subscription",  
  "has_payment_method": true,  
  "soft_limit_usd": 100.0,  
  "hard_limit_usd": 100.0,  
  "system_hard_limit_usd": 100.0,  
  "access_until": 1640995200  
}
```

#### ❗ 失败响应示例：

```json
{  
  "error": {  
    "message": "获取配额失败",  
    "type": "upstream_error"  
  }  
}
```

#### 🧾 字段说明：

- **object** （字符串）: 固定值"billing_subscription"
- **has_payment_method** （布尔型）: 是否有支付方式，固定为 true
- **soft_limit_usd** （数字）: 软限制额度（美元）
- **hard_limit_usd** （数字）: 硬限制额度（美元）
- **system_hard_limit_usd** （数字）: 系统硬限制额度（美元）
- **access_until** （数字）: 访问有效期时间戳，Token 过期时间

### 兼容 OpenAI SDK 路径 - 获取订阅额度信息

- **接口名称**：兼容 OpenAI SDK 路径 - 获取订阅额度信息
- **HTTP 方法**：GET
- **路径**：`/v1/dashboard/billing/subscription`
- **鉴权要求**：用户 Token
- **功能简介**：与上述接口功能完全相同，提供 OpenAI SDK 兼容路径

#### 💡 请求示例：

```javascript
const response = await fetch('/v1/dashboard/billing/subscription', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "object": "billing_subscription",  
  "has_payment_method": true,  
  "soft_limit_usd": 100.0,  
  "hard_limit_usd": 100.0,  
  "system_hard_limit_usd": 100.0,  
  "access_until": 1640995200  
}
```

#### ❗ 失败响应示例：

```json
{  
  "error": {  
    "message": "获取配额失败",  
    "type": "upstream_error"  
  }  
}
```

#### 🧾 字段说明：

- **object** （字符串）: 固定值"billing_subscription"
- **has_payment_method** （布尔型）: 是否有支付方式，固定为 true
- **soft_limit_usd** （数字）: 软限制额度（美元）
- **hard_limit_usd** （数字）: 硬限制额度（美元）
- **system_hard_limit_usd** （数字）: 系统硬限制额度（美元）
- **access_until** （数字）: 访问有效期时间戳，Token 过期时间

### 获取使用量信息

- **接口名称**：获取使用量信息
- **HTTP 方法**：GET
- **路径**：`/dashboard/billing/usage`
- **鉴权要求**：用户 Token
- **功能简介**：获取用户的配额使用量信息，兼容 OpenAI API 格式

#### 💡 请求示例：

```javascript
const response = await fetch('/dashboard/billing/usage', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "object": "list",  
  "total_usage": 2500.0  
}
```

#### ❗ 失败响应示例：

```json
{  
  "error": {  
    "message": "获取使用量失败",  
    "type": "new_api_error"  
  }  
}
```

#### 🧾 字段说明：

- **object** （字符串）: 固定值"list"
- **total_usage** （数字）: 总使用量，单位为 0.01 美元

### 兼容 OpenAI SDK 路径 - 获取使用量信息

- **接口名称**：兼容 OpenAI SDK 路径 - 获取使用量信息
- **HTTP 方法**：GET
- **路径**：`/v1/dashboard/billing/usage`
- **鉴权要求**：用户 Token
- **功能简介**：与上述接口功能完全相同，提供 OpenAI SDK 兼容路径

#### 💡 请求示例：

```javascript
const response = await fetch('/v1/dashboard/billing/usage', {  
  method: 'GET',  
  headers: {  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer your_user_token',
    'New-Api-User': 'Bearer your_user_id'
  }  
});  
const data = await response.json();
```

#### ✅ 成功响应示例：

```json
{  
  "object": "list",  
  "total_usage": 2500.0  
}
```

#### ❗ 失败响应示例：

```json
{  
  "error": {  
    "message": "获取使用量失败",  
    "type": "new_api_error"  
  }  
}
```

#### 🧾 字段说明：

- **object** （字符串）: 固定值"list"
- **total_usage** （数字）: 总使用量，单位为 0.01 美元