Vidora 短剧管理后台

API 简介

Vidora 短剧数据服务提供标准化的 RESTful API，用于获取短剧视频数据。所有接口均返回 JSON 格式数据，支持分页、分类筛选和搜索功能。

📌 基础 URL: http://localhost:8088/api

API 认证

⚠️ 所有 API 端点（除 /health 外）都需要提供有效的 API Key

请在请求头中添加 Authorization: Bearer YOUR_API_KEY

API 端点

GET/api/health

健康检查接口，用于验证服务是否正常运行。

响应示例: {"success": true, "status": "healthy", "timestamp": "..."}

GET/list

获取视频列表（精简字段）。

查询参数:

page - 页码（默认: 1）
pageSize - 每页数量（默认: 20，最大: 100）
tag - 标签名称（二级分类，从 categories API 获取）

请求示例 (curl):

# 查询所有视频 curl -H "Authorization: Bearer YOUR_API_KEY" \ "http://localhost:8088/api/list?page=1&pageSize=20" # 按标签查询（二级分类） curl -H "Authorization: Bearer YOUR_API_KEY" \ "http://localhost:8088/api/list?tag=甜宠&page=1&pageSize=20" # 注意：一级分类仅用于展示，实际查询使用 tag 参数

GET/detail/:id

获取视频详情（完整字段）。

路径参数:

id - 视频 vod_id

请求示例 (curl):

curl -H "Authorization: Bearer YOUR_API_KEY" \ "http://localhost:8088/api/detail?vodId=27196"

GET/categories

获取所有分类（包含一级分类和二级分类）。

请求示例 (curl):

curl -H "Authorization: Bearer YOUR_API_KEY" \ "http://localhost:8088/api/categories"

📌 使用说明：

• 一级分类仅用于展示和分组，不直接关联视频
• 二级分类的 name 字段用作 tag 参数
• 客户端应缓存分类数据，使用 version 检测更新

响应示例:

{ "success": true, "data": [ { "id": 1, "name": "都市短剧", "sort": 0, "is_active": true, "sub_categories": [ { "id": 1, "name": "甜宠" }, { "id": 2, "name": "虐恋" } ] } ], "version": 1 }

GET/search

搜索视频（支持标题和描述）。

查询参数:

keyword - 搜索关键词（必需）
page - 页码（默认: 1）
pageSize - 每页数量（默认: 20，最大: 100）

请求示例 (curl):

curl -H "Authorization: Bearer YOUR_API_KEY" \ "http://localhost:8088/api/search?keyword=总裁&page=1&pageSize=20"

响应格式

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 26970,
    "totalPages": 1349
  }
}

列表返回字段

视频列表（/list）

• vod_id - 视频 ID
• name - 片名
• category_id - 一级分类 ID
• tags - 标签数组
• episode_count - 总集数
• cover - 海报图片
• score - 评分
• score_num - 评分人数
• hits - 点击数
• updated_at - 更新时间

视频详情（/detail）

• 包含列表所有字段
• description - 简介
• play_urls - 播放链接数组
• actor - 演员
• director - 导演
• writer - 编剧
• area - 地区
• lang - 语言
• year - 年份
• hits_day - 日点击
• hits_week - 周点击
• hits_month - 月点击
• up - 点赞数
• down - 下载数

错误码

状态码	说明
`200`	成功
`400`	请求参数错误
`404`	资源不存在
`500`	服务器内部错误
`503`	服务不可用

注意事项

•所有接口需认证访问
•建议客户端实现缓存机制，减少重复请求
•分页参数 page 从 1 开始
•播放链接格式: [{"episode": 1, "url": "https://..."}, ...]
•数据更新频率: 每日定时同步