抖音直播助手 - 接口说明文档

本文档描述了前端（抖音直播助手）与后端之间的接口通信规范，用于支持以下功能：
- Token验证：用户输入Token进行身份验证。
- 查询抖音号：通过抖音号查询用户信息。
- 抖音功能：获取抖音用户信息、获取直播创建信息、检查直播状态、准备腾讯云推流配置、创建直播间、关闭直播间。
- 定时任务：设置和获取自动开播/关播时间。
- 代理设置：设置和获取指定抖音号的代理IP。

前端使用fetch进行HTTP请求，期望后端返回JSON格式的响应数据。所有请求均携带Authorization头，使用Bearer Token进行身份验证。Token仅用于身份验证，不与抖音号绑定，前端可在请求中指定任意douyin_id进行操作。

通用规范

请求头

• Authorization: Bearer ：所有接口（除/auth/verify-token外）都需要携带Token。
• Accept: application/json：期望接收JSON格式的响应。
• Content-Type: application/json：POST和PUT请求的请求体为JSON格式。

请求参数

• 所有接口（包括GET请求）均需传递douyin_id，用于指定操作的抖音号。
• douyin_id通过请求体（POST/PUT）或查询参数（GET）传递。

响应格式

成功响应：

{
    "success": true,
    "data": { /* 具体数据 */ }
}
        

错误响应：

{
    "success": false,
    "detail": "错误信息"
}
        

状态码：

• 200：成功。
• 400：参数错误。
• 401：Token无效或未登录。
• 500：服务器内部错误。

时间格式

时间戳使用Unix时间戳（秒），如1625097600。

接口列表

1. 验证Token

GET /auth/verify-token

用途：验证用户输入的Token是否有效，用于登录。

请求头：

• Authorization: Bearer

请求参数：无

响应示例：

成功：

{
    "success": true
}
        

失败（Token无效）：

{
    "success": false,
    "detail": "无效的Token"
}
        

状态码：401

2. 查询抖音号

POST /douyin/query

用途：根据抖音号查询用户信息，用于显示抖音昵称和签名。

请求头：

• Authorization: Bearer
• Content-Type: application/json

请求体：

{
    "douyin_id": "123456" // 抖音号，字符串
}
        

响应示例：

成功：

{
    "success": true,
    "data": {
        "nickname": "用户_123456", // 抖音昵称，字符串
        "signature": "这是123456的签名" // 抖音签名，字符串
    }
}
        

失败（抖音号不存在）：

{
    "success": false,
    "detail": "抖音号不存在"
}
        

状态码：400

3. 获取抖音用户信息

GET /douyin/user/info

用途：获取指定抖音号的详细信息。

请求头：

• Authorization: Bearer

查询参数：

• douyin_id：抖音号，字符串，例如?douyin_id=123456

响应示例：

成功：

{
    "success": true,
    "data": {
        "nickname": "Mock用户", // 抖音昵称，字符串
        "signature": "Mock签名，欢迎体验！" // 抖音签名，字符串
    }
}
        

失败（抖音号不存在）：

{
    "success": false,
    "detail": "抖音号不存在"
}
        

状态码：400

4. 获取直播创建信息

GET /douyin/live/create-info

用途：获取指定抖音号的直播默认标题和封面信息，用于用户编辑。

请求头：

• Authorization: Bearer

查询参数：

• douyin_id：抖音号，字符串，例如?douyin_id=123456

响应示例：

成功：

{
    "success": true,
    "data": {
        "title": "Mock直播标题", // 默认直播标题，字符串
        "cover": {
            "uri": "https://example.com/mock_cover.jpg" // 封面图片URL，字符串
        }
    }
}
        

失败（抖音号不存在）：

{
    "success": false,
    "detail": "抖音号不存在"
}
        

状态码：400

5. 检查直播状态

GET /douyin/status/live

用途：检查指定抖音号是否正在直播，获取直播间ID。

请求头：

• Authorization: Bearer

查询参数：

• douyin_id：抖音号，字符串，例如?douyin_id=123456

响应示例：

成功（正在直播）：

{
    "success": true,
    "is_live": true,
    "open_room_id": "room_1625097600" // 直播间ID，字符串
}
        

成功（未直播）：

{
    "success": true,
    "is_live": false,
    "open_room_id": null
}
        

失败（抖音号不存在）：

{
    "success": false,
    "detail": "抖音号不存在"
}
        

状态码：400

6. 准备腾讯云推流配置

POST /douyin/live/prepare-tencent

用途：为指定抖音号的直播生成腾讯云推流地址。

请求头：

• Authorization: Bearer
• Content-Type: application/json

请求体：

{
    "douyin_id": "123456" // 抖音号，字符串
}
        

响应示例：

成功：

{
    "success": true,
    "data": {
        "push_url_a": "rtmp://push.example.com/live/stream_key?token=abc123" // 推流地址，字符串
    }
}
        

失败（抖音号不存在）：

{
    "success": false,
    "detail": "抖音号不存在"
}
        

状态码：400

7. 创建直播间

POST /douyin/live/create

用途：为指定抖音号创建直播间，返回直播间ID和推流地址。

请求头：

• Authorization: Bearer
• Content-Type: application/json

请求体：

{
    "douyin_id": "123456", // 抖音号，字符串
    "cover_uri": "https://example.com/cover.jpg", // 直播封面URL，字符串
    "title": "我的直播标题" // 直播标题，字符串
}
        

响应示例：

成功：

{
    "success": true,
    "data": {
        "open_room_id": "room_1625097600", // 直播间ID，字符串
        "user_obs_push_url": "rtmp://push.example.com/live/stream_key_tencent?token=xyz789", // 腾讯云推流地址，字符串
        "mode": "tencent", // 推流模式，字符串（固定为"tencent"）
        "tencent_task_status": "created" // 腾讯云任务状态，字符串
    }
}
        

失败（参数错误）：

{
    "success": false,
    "detail": "缺少必要参数"
}
        

状态码：400

8. 关闭直播间

POST /douyin/live/close

用途：关闭指定抖音号的当前直播间。

请求头：

• Authorization: Bearer
• Content-Type: application/json

请求体：

{
    "douyin_id": "123456" // 抖音号，字符串
}
        

响应示例：

成功：

{
    "success": true,
    "detail": "直播已关闭"
}
        

失败（无直播）：

{
    "success": false,
    "detail": "当前无直播"
}
        

状态码：400

9. 获取定时任务设置

GET /douyin/schedule

用途：获取指定抖音号的定时开播和关播设置。

请求头：

• Authorization: Bearer

查询参数：

• douyin_id：抖音号，字符串，例如?douyin_id=123456

响应示例：

成功：

{
    "success": true,
    "scheduled_start_enabled": true, // 是否启用定时开播，布尔值
    "scheduled_start_time": 1625097600, // 定时开播时间，Unix时间戳（秒），可为null
    "scheduled_stop_enabled": false, // 是否启用定时关播，布尔值
    "scheduled_stop_time": null // 定时关播时间，Unix时间戳（秒），可为null
}
        

失败（抖音号不存在）：

{
    "success": false,
    "detail": "抖音号不存在"
}
        

状态码：400

10. 设置定时任务

PUT /douyin/schedule

用途：设置指定抖音号的定时开播和关播时间。

请求头：

• Authorization: Bearer
• Content-Type: application/json

请求体：

{
    "douyin_id": "123456", // 抖音号，字符串
    "start_enabled": true, // 是否启用定时开播，布尔值
    "start_time": 1625097600, // 定时开播时间，Unix时间戳（秒），可为null
    "stop_enabled": false, // 是否启用定时关播，布尔值
    "stop_time": null // 定时关播时间，Unix时间戳（秒），可为null
}
        

响应示例：

成功：

{
    "success": true
}
        

失败（时间无效）：

{
    "success": false,
    "detail": "无效的开播时间或时间已过"
}
        

状态码：400

11. 获取代理设置

GET /douyin/proxy

用途：获取指定抖音号的代理IP设置。

请求头：

• Authorization: Bearer

查询参数：

• douyin_id：抖音号，字符串，例如?douyin_id=123456

响应示例：

成功（已设置代理）：

{
    "success": true,
    "data": {
        "proxy_ip": "192.168.1.1:8080" // 代理IP，字符串
    }
}
        

成功（未设置代理）：

{
    "success": true,
    "data": {
        "proxy_ip": null
    }
}
        

失败（抖音号不存在）：

{
    "success": false,
    "detail": "抖音号不存在"
}
        

状态码：400

12. 设置代理IP

PUT /douyin/proxy

用途：设置或清除指定抖音号的代理IP。

请求头：

• Authorization: Bearer
• Content-Type: application/json

请求体：

{
    "douyin_id": "123456", // 抖音号，字符串
    "proxy_ip": "192.168.1.1:8080" // 代理IP，字符串，可为null（表示清除代理）
}
        

响应示例：

成功：

{
    "success": true
}
        

失败（抖音号不存在）：

{
    "success": false,
    "detail": "抖音号不存在"
}
        

状态码：400

注意事项

Token验证

• 所有接口（除/auth/verify-token外）需验证Token，若Token无效，返回401状态码和错误信息。
• Token不与抖音号绑定，仅用于身份验证，后端应允许通过Token查询任意抖音号。

抖音号传递

• 每个接口（包括GET）都需要显式传递douyin_id，后端根据此字段操作。
• douyin_id为空或不存在时，返回400错误，提示“缺少抖音号”。

错误处理

• 后端需提供明确的错误信息（detail字段），前端会显示给用户。
• 常见错误包括：参数缺失、时间无效、抖音号不存在、未登录等。

时间戳

所有时间戳使用Unix时间戳（秒），前端会将其转换为本地时间显示。

测试建议

Mock数据

• 后端可使用Mock数据测试接口，例如固定Token（test_token）和抖音号（123456）。
• 模拟各种成功和失败场景，确保前端能正确处理。

边界测试

• 测试无效Token（如空Token、错误Token）。
• 测试无效时间戳（如过去的时间）。
• 测试douyin_id为空或不存在的情况。
• 测试不同抖音号的查询，确保Token可操作任意抖音号。

性能测试

• 检查接口响应时间，确保在500ms内返回。
• 测试并发请求，确保Token验证和抖音号处理逻辑正确。