JieXi/API文档.md

# 短视频解析平台 - API 文档

## 基础信息

- 基础URL: `http://your-domain.com`
- 数据格式: JSON
- 字符编码: UTF-8

## 认证相关 API

### 1. 发送验证码

**接口地址**: `/auth/send-code`

**请求方法**: `POST`

**请求参数**:

```json
{
  "email": "user@example.com",
  "purpose": "register"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| email | string | 是 | 邮箱地址 |
| purpose | string | 是 | 用途：register/reset_password/forgot_password |

**响应示例**:

```json
{
  "success": true,
  "message": "验证码已发送"
}
```

### 2. 用户注册

**接口地址**: `/auth/register`

**请求方法**: `POST`

**请求参数**:

```json
{
  "username": "testuser",
  "email": "user@example.com",
  "password": "password123",
  "code": "123456"
}
```

**响应示例**:

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

### 3. 用户登录

**接口地址**: `/auth/login`

**请求方法**: `POST`

**请求参数**:

```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**响应示例**:

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

### 4. 用户登出

**接口地址**: `/auth/logout`

**请求方法**: `POST`

**需要登录**: 是

**响应示例**:

```json
{
  "success": true,
  "message": "已退出登录"
}
```

### 5. 重置密码

**接口地址**: `/auth/reset-password`

**请求方法**: `POST`

**请求参数**:

```json
{
  "email": "user@example.com",
  "code": "123456",
  "new_password": "newpassword123"
}
```

**响应示例**:

```json
{
  "success": true,
  "message": "密码重置成功"
}
```

## 解析相关 API

### 1. 解析视频

**接口地址**: `/api/parse`

**请求方法**: `POST`

**请求参数**:

```json
{
  "url": "https://v.douyin.com/xxxxx/"
}
```

**响应示例（立即完成）**:

```json
{
  "success": true,
  "status": "completed",
  "data": {
    "cover": "https://...",
    "video_url": "https://...",
    "title": "视频标题",
    "description": "视频描述"
  },
  "response_time": 1234
}
```

**响应示例（排队中）**:

```json
{
  "success": true,
  "status": "queued",
  "task_id": "uuid-string",
  "message": "任务已加入队列，请稍候...",
  "queue_status": {
    "queued": 5,
    "processing": 3
  }
}
```

### 2. 获取任务结果

**接口地址**: `/api/task/<task_id>`

**请求方法**: `GET`

**响应示例**:

```json
{
  "success": true,
  "status": "completed",
  "data": {
    "cover": "https://...",
    "video_url": "https://...",
    "title": "视频标题",
    "description": "视频描述"
  }
}
```

### 3. 获取队列状态

**接口地址**: `/api/queue-status`

**请求方法**: `GET`

**响应示例**:

```json
{
  "success": true,
  "queue_status": {
    "queued": 5,
    "processing": 3
  }
}
```

## 管理员 API

### 1. 管理员登录

**接口地址**: `/admin/login`

**请求方法**: `POST`

**请求参数**:

```json
{
  "username": "admin",
  "password": "password",
  "code_2fa": "123456"
}
```

### 2. 获取仪表板数据

**接口地址**: `/admin/dashboard`

**请求方法**: `GET`

**需要管理员权限**: 是

**响应示例**:

```json
{
  "success": true,
  "data": {
    "today": {
      "total": 100,
      "success": 95,
      "fail": 5
    },
    "total_users": 50,
    "total_parses": 1000,
    "active_apis": 5
  }
}
```

### 3. 获取用户列表

**接口地址**: `/admin/users`

**请求方法**: `GET`

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| per_page | int | 否 | 每页数量，默认20 |

### 4. 更新用户信息

**接口地址**: `/admin/users/<user_id>`

**请求方法**: `PUT`

**请求参数**:

```json
{
  "group_id": 3,
  "is_active": true
}
```

### 5. 获取解析接口列表

**接口地址**: `/admin/apis`

**请求方法**: `GET`

### 6. 创建解析接口

**接口地址**: `/admin/apis`

**请求方法**: `POST`

**请求参数**:

```json
{
  "name": "接口名称",
  "platform": "douyin",
  "api_url": "https://api.example.com",
  "api_key": "optional-key",
  "weight": 1,
  "is_enabled": true
}
```

### 7. 更新站点配置

**接口地址**: `/admin/config`

**请求方法**: `PUT`

**请求参数**:

```json
{
  "site_title": "短视频解析平台",
  "max_concurrent": "5"
}
```

### 8. 测试SMTP配置

**接口地址**: `/admin/smtp/test`

**请求方法**: `POST`

**请求参数**:

```json
{
  "email": "test@example.com"
}
```

### 9. 获取解析统计

**接口地址**: `/admin/stats/parse`

**请求方法**: `GET`

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| days | int | 否 | 统计天数，默认7 |

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权/登录失败 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器错误 |

## 限流说明

- 游客：每天最多解析 5 次
- 普通用户：每天最多解析 10 次
- VIP用户：每天最多解析 50 次
- SVIP用户：每天最多解析 200 次

管理员可在后台自定义各分组的限流策略。

## 支持的平台

- 抖音 (douyin)
- TikTok (tiktok)
- 哔哩哔哩 (bilibili)

## 注意事项

1. 所有 POST 请求需要设置 `Content-Type: application/json`
2. 需要登录的接口会返回 401 错误码
3. 超过限流次数会返回 429 错误码
4. 解析任务可能需要排队，请使用轮询方式获取结果