API 文档

漫剧榜开放 API 供开发者、MCP 客户端和 AI Agent 访问短剧广告投放数据。

Base URLhttps://superline.video/api/v1

数据格式JSON（UTF-8）

更新频率每日 06:00–08:00 CST 更新前一日数据

鉴权方式

所有接口均可不带鉴权访问（游客模式），但返回数据受限。携带 API Key 后可获取完整数据。

使用 API Key（推荐）

在请求头中添加 X-API-Key：

HTTP

GET /api/v1/dramas
X-API-Key: mjb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

使用 JWT Bearer Token

通过登录接口获取 access_token，有效期 30 分钟：

HTTP

GET /api/v1/dramas
Authorization: Bearer <access_token>

💡在个人中心可查看、复制、轮换你的 API Key。每个账号最多 5 个。

访问层级

接口根据鉴权状态返回不同数量的数据：

数据类型	游客（无 Key）	API Key / 已登录
剧目列表	最多 10 条，仅第 1 页	最多 100 条/页，全量翻页
剧目历史数据	近 30 天	全量历史
趋势列表	最多 10 条	全量
标签概览	最多 15 条	全量
标签趋势	最多 7 天 / 3 个标签	最多 90 天 / 10 个标签
剧目对比	不可用（403）	可用
数据导出（Excel）	不可用（401）	可用

限制状态通过响应体中的 access_metadata 字段透出：

JSON

{
  "items": [...],
  "total": 428,
  "access_metadata": {
    "access_tier": "guest",       // "guest" | "session" | "api_key"
    "is_limited": true,
    "limit_reason": "guest_limit",
    "upgrade_message": "登录或使用 API Key 查看完整数据",
    "returned_count": 10,
    "full_count_known": false
  }
}

剧目数据

GET/dramas剧目排行列表

查询参数

参数	类型	默认	说明
`date`	date	最新日期	数据日期，格式 `YYYY-MM-DD`
`sort`	string	`creative_count`	排序字段：`creative_count` / `impression` / `heat`
`period`	string	`day`	统计周期：`day` / `week` / `month`
`tags`	string	—	标签筛选，逗号分隔，如 `甜宠,总裁`
`keyword`	string	—	剧名关键词搜索
`advertiser`	string	—	投放方名称筛选
`country`	string	—	国家/地区
`page`	int	`1`	页码（游客仅第 1 页）
`size`	int	`20`	每页条数，最大 100（游客最多 10）

响应示例

JSON

{
  "items": [
    {
      "id": 1234,
      "drama_name": "霸总的小娇妻",
      "drama_name_zh": "霸总的小娇妻",
      "tags": "甜宠,总裁,现代",
      "creative_count": 8520,
      "impression": 12400000,
      "heat": 95.3,
      "rank": 1,
      "thumbnail_url": "https://..."
    }
  ],
  "total": 428,
  "page": 1,
  "size": 20,
  "access_metadata": { ... }
}

GET/dramas/{id}剧目详情

返回剧目基础信息及历史每日数据。游客仅返回近 30 天数据。

JSON

{
  "id": 1234,
  "drama_name": "霸总的小娇妻",
  "tags": "甜宠,总裁",
  "thumbnail_url": "https://...",
  "style_tags": ["现代都市", "甜宠"],
  "daily_stats": [
    {
      "date": "2026-03-29",
      "creative_count": 8520,
      "impression": 12400000,
      "heat": 95.3,
      "rank": 1
    }
  ]
}

GET/dramas/{id}/trend剧目趋势数据

参数	类型	说明
`start`	date	起始日期（游客限近 30 天）
`end`	date	截止日期

JSON

{
  "dates": ["2026-03-01", "2026-03-02", ...],
  "creative_count": [7200, 7850, ...],
  "impression": [11000000, 12400000, ...],
  "heat": [88.1, 91.5, ...],
  "rank": [3, 2, ...]
}

GET/dramas/compare多剧目对比需要鉴权

参数	类型	说明
`ids`	string	剧目 ID，逗号分隔，2–4 个，如 `1234,5678`
`start`	date	起始日期
`end`	date	截止日期

GET/dramas/export导出 Excel 需要鉴权

返回 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 格式文件，支持 date/tags/advertiser/country/keyword 筛选参数。

趋势分析

GET/trends/explosions今日爆量剧目

当日投放量相较前日增速最快的剧目。游客最多 10 条。

参数	类型	说明
`date`	date	数据日期，默认最新日期

JSON

{
  "items": [
    {
      "id": 1234,
      "name": "霸总的小娇妻",
      "tags": "甜宠,总裁",
      "prev_count": 3200,
      "today_count": 8520,
      "growth_rate": 1.66
    }
  ],
  "access_metadata": { ... }
}

GET/trends/new-dramas新上榜剧目

参数	类型	说明
`date`	date	截止日期
`days`	int	近 N 天内首次出现，默认 3，最大 30

GET/trends/declining衰退剧目

投放量相较历史峰值已明显下滑的剧目。参数同爆量接口。

标签数据

GET/tags/overview标签分布概览

各标签当日在投剧目数量。游客最多 15 个标签，API Key 用户全量。

JSON

{
  "items": [
    { "name": "甜宠", "count": 84 },
    { "name": "总裁", "count": 61 }
  ],
  "access_metadata": { ... }
}

GET/tags/trends标签趋势时序

参数	类型	说明
`start`	date	起始日期（游客限 7 天内）
`end`	date	截止日期
`tags`	string	指定标签，逗号分隔（游客最多 3 个）
`limit`	int	返回标签数，默认 10，最大 30

JSON

{
  "dates": ["2026-03-23", "2026-03-24", ...],
  "series": [
    { "tag": "甜宠", "data": [78, 82, 84, ...] }
  ],
  "access_metadata": { ... }
}

GET/tags/countries地区分布

各国家/地区当日在投剧目数量。参数：date。

GET/tags/channels渠道分布

各投放渠道当日在投剧目数量。参数：date。

PineDrama

PineDrama 接口提供短剧内容库和播放量排行数据，包含剧名、封面、分类、总集数、播放量、简介和本地处理统计。接口不会返回 NAS 内网路径或视频下载地址。

GET/pinedrama/statsPineDrama 总体统计

返回当前已入库 PineDrama 剧集的规模、总播放量、总集数和简介覆盖情况。

JSON

{
  "drama_count": 435,
  "episode_count": 24443,
  "total_watched": 15940861075,
  "total_size_mb": 260310,
  "with_description": 431,
  "missing_description": 4
}

GET/pinedrama/dramasPineDrama 剧集列表和排行榜

默认按播放量倒序返回，可用于构建播放量排行榜、按关键词检索剧名和题材。

查询参数

参数	类型	默认	说明
`page`	int	`1`	页码，从 1 开始
`size`	int	`20`	每页条数，最大 100
`sort`	string	`num_watched`	排序字段：`num_watched` / `num_videos` / `total_size_mb` / `title`
`keyword`	string	—	按剧名、中文分类或英文分类模糊搜索

响应示例

JSON

{
  "items": [
    {
      "id": 58,
      "collection_id": "7589198057766638613",
      "title": "When Broken Hearts Beat Again",
      "num_videos": 65,
      "num_watched": 299261454,
      "categories": "现代, 小人物, 纠葛虐恋",
      "categories_en": "High society, Reconciliation, Regretful chase",
      "category_type": "MINI_DRAMA",
      "is_limited_free": true,
      "cover_url": "/thumbnails/pinedrama/7589198057766638613.jpg",
      "status": "pending",
      "description": "Seeking a quiet life away from her family's massive corporate empire...",
      "episode_count": 66,
      "total_size_mb": 451.4,
      "avg_duration_sec": 74.0
    }
  ],
  "total": 435,
  "page": 1,
  "size": 20
}

💡num_videos 是剧方标称总集数，episode_count 是当前本地处理到的集数统计。前端榜单默认展示总集数。

用户信息

GET/auth/me当前用户信息需要鉴权

可用于验证 API Key 是否有效。

JSON

{
  "id": 42,
  "email": "you@example.com",
  "nickname": "你的昵称",
  "is_active": true
}