小影API 小影API

短剧

短剧服务：提供短剧的榜单、分类、搜索、详情与播放直链能力，按「榜单/分类 → 列表 → 详情 → 播放」流程即可搭建短剧站。

/api/dramas/

服务说明

短剧服务聚合短剧站数据，提供榜单、分类、搜索、详情与播放直链等能力，按「榜单/分类 → 列表 → 详情 → 播放」的顺序即可搭起一个短剧站，搜索接口则支持按剧名关键词查剧。

播放能力：前 3 集由源站直接下发明文直链（源站仅 360p）；第 4 集及以后源站只下发DRM 加密的 H.265，由本服务在服务端解密后实时中转出流 —— 拿到播放地址后请求它就开始出数据（实测首块 0.3 秒），不需要等整集生成。

出流编码按客户端能力二选一：codec=hevc 只解密+重新封装、不重编码（画质是源站原画，小程序 / App / iOS / Android 都能解，服务端几乎不耗 CPU）；codec=h264 实时重编码（桌面浏览器兜底，首帧约 1~2 秒）。

首次点播是「边解密边发」：请求地址就开始出数据，不用等整集生成；这一遍转完会把整集留成缓存产物，之后再请求同一个地址就是标准文件出流 —— 支持 HTTP Range 拖动、可从上次位置继续，暂停很久或关掉页面后再回来也不会从头。视频很短时基本感觉不到差别。若所用播放器对分片流兼容性不佳（部分 iOS / 小程序播放器），可传 mode=file，由服务端先生成整集文件再整文件出流（首次需等待）。

播放接口返回的源站直链为 MP4 且带时效，请勿在客户端长期缓存；剧集元数据与集列表缓存较久，播放直链缓存较短以便及时刷新。本服务需项目签名。

响应格式

所有接口返回同一个 JSON 信封，业务数据都在 data 里： 

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}
  • code：业务状态码，10000 表示成功；其余为各类错误，完整清单见「错误码」页。
  • msg：给人看的提示文案，可直接展示给终端用户，但不要用它做逻辑判断。
  • data：业务数据；出错时通常为 null。各接口 data 的具体字段见该接口的「响应说明」。

判断成功与否请看 code，不要依赖 HTTP 状态码。 查看完整错误码

红果短剧

红果短剧（hongguoduanju.com）网页版 需签名

实时爬取源站 SSR 数据并缓存。剧集元数据/集列表缓存较久；播放直链缓存较短。

GET /api/dramas/hongguo/rank 累计调用 8 次

榜单

获取短剧榜单，支持热播榜 / 真人剧热播榜 / AI剧热播榜 / 漫剧热播榜与分页。

可选：榜单类型，默认 hot-drama（热播榜）。

可选：页码，从 1 开始，默认 1。

  • 榜单类型非法时返回 PARAM_VALUE_INVALID。
  • 返回 data 为榜单剧集列表（字段与「分类列表」接口一致）。
响应说明 外层统一格式
字段 类型 说明
type string 榜单类型（回带入参）
page int 当前页码
total_page int 总页数
results array 榜单剧集列表
results[].rank int 排名
results[].series_id string 剧集 ID（传给详情/播放接口）
results[].name string 剧名
results[].cover string 封面图地址
results[].url string 详情页地址
results[].heat string 热度（无则 null）
results[].score string 评分（无则 null）
results[].favorite string 收藏数（无则 null）
results[].like string 点赞数（无则 null）
results[].tags array 题材标签
results[].intro string 剧情简介
返回示例 
{
  "type": "hot-drama",
  "page": 1,
  "total_page": 3,
  "results": [
    {"rank": 1, "series_id": "7686894628578020414", "name": "示例短剧", "cover": "https://img.example.com/1.jpg", "url": "https://www.hongguoduanju.com/detail/7686894628578020414", "heat": "1234", "score": "9.2", "favorite": "120", "like": "56", "tags": ["逆袭", "甜宠"], "intro": ""}
  ]
}
GET /api/dramas/hongguo/categories 累计调用 1 次

分类清单

获取分类树（一级 -> 二级题材）。

  • 分类是两级的：一级是内容形态（真人剧 / 漫剧 / AI剧 / 漫画），二级是题材（爱情 / 年代 / 逆袭 …）。
  • 每个节点的 slug 都可直接传给「分类列表」接口的 category：一级取该一级全部，二级只取该题材（形如 real-drama/romance）；无二级的一级（漫画）children 为空数组。
响应说明 外层统一格式
字段 类型 说明
categories array 分类树（一级）
categories[].slug string 一级分类标识（传给列表接口 category）
categories[].name string 一级分类名称
categories[].url string 分类页地址
categories[].children array 二级题材（无则为空数组）
categories[].children[].slug string 二级标识（一级/二级形式）
categories[].children[].name string 二级题材名称
categories[].children[].url string 分类页地址
返回示例 
{
  "categories": [
    {"slug": "real-drama", "name": "真人剧", "url": "https://www.hongguoduanju.com/category/real-drama", "children": [
      {"slug": "real-drama/romance", "name": "爱情", "url": "https://www.hongguoduanju.com/category/real-drama/romance"}
    ]}
  ]
}
GET /api/dramas/hongguo/list 累计调用 4 次

分类列表

按分类获取短剧列表，支持分页。

必填：分类取值 —— 一级 slug（如 real-drama）或「一级/二级」（如 real-drama/romance），完整取值见「分类清单」接口。

可选：页码，从 1 开始，默认 1。

  • category 缺失或非法时返回 PARAM_MISSING / PARAM_VALUE_INVALID。
响应说明 外层统一格式
字段 类型 说明
category string 分类标识（回带入参）
page int 当前页码
results array 短剧列表
results[].series_id string 剧集 ID（传给详情/播放接口）
results[].name string 剧名
results[].cover string 封面图地址
results[].url string 详情页地址
results[].tags array 题材标签
results[].intro string 剧情简介
results[].rank null 榜单专有字段，列表接口恒为 null
results[].heat null 榜单专有字段，列表接口恒为 null
results[].score null 榜单专有字段，列表接口恒为 null
results[].favorite null 榜单专有字段，列表接口恒为 null
results[].like null 榜单专有字段，列表接口恒为 null
pagination object 分页信息
pagination.current int 当前页码
pagination.total int 总页数
返回示例 
{
  "category": "real-drama",
  "page": 1,
  "results": [
    {"series_id": "7686894628578020414", "name": "示例短剧", "cover": "https://img.example.com/1.jpg", "url": "https://www.hongguoduanju.com/detail/7686894628578020414", "tags": ["逆袭"], "intro": "", "rank": null, "heat": null, "score": null, "favorite": null, "like": null}
  ],
  "pagination": {"current": 1, "total": 2}
}
GET /api/dramas/hongguo/detail 累计调用 71 次

剧集详情

获取剧集详情与全量集列表。

必填：剧集 ID（取自列表/搜索结果）。

  • 返回 data.episodes 为全量集列表，每项含 ep / episode_id / playable / source。
  • episodes[].playable 的口径与「播放地址」接口完全一致：源站直链 / 本站网页直出两条路任一可用即为 true；source 标出走的哪条路 —— origin（源站直链）/ stream（本站直出，首播需等数十秒生成）。本站直出默认可用，所以第 4 集及以后通常也是 playable=true。
  • data.playable_cnt 为源站直链的连续范围（前 N 集，保持原义）；data.listed_cnt 为实际可播集数（= playable 为 true 的集数）。需要判断「某集能不能播」请用 episodes[].playable，不要用 playable_cnt 推算。
  • 剧集不存在时返回 EXTERNAL_API_FAILED（外部API调用失败）。
响应说明 外层统一格式
字段 类型 说明
series_id string 剧集 ID（回带入参）
name string 剧名
cover string 封面图地址
intro string 剧情简介
tags array 题材标签
episode_cnt int 总集数
playable_cnt int 源站直链的连续可播集数
listed_cnt int 实际可播集数（playable=true 的集数）
episodes array 全量集列表
episodes[].ep int 集号（从 1 开始）
episodes[].episode_id string 源站集 ID
episodes[].playable bool 该集是否可播
episodes[].source string 来源：origin 源站直链 / stream 本站直出
返回示例 
{
  "series_id": "7686894628578020414",
  "name": "示例短剧",
  "cover": "https://img.example.com/1.jpg",
  "intro": "",
  "tags": ["逆袭"],
  "episode_cnt": 60,
  "playable_cnt": 3,
  "listed_cnt": 60,
  "episodes": [
    {"ep": 1, "episode_id": "123", "playable": true, "source": "origin"},
    {"ep": 4, "episode_id": "456", "playable": true, "source": "stream"}
  ]
}
GET /api/dramas/hongguo/play 累计调用 113 次

播放地址

获取指定集的播放地址（网页可直接播放）。

必填：集数，从 1 开始。

选填：出流画质（= 输出宽度上限；短剧是竖屏，1080 即 1080×1920，也就是日常说的 1080p）。指定了高于源站公开 mp4 的画质（源站仅 360p）时，改用本站「网页直出」出到该画质；未指定、或不高于源站时直接用源站直链（360p）。每档产物各存一份；换画质要重新调本接口换地址。

选填：本站直出时用什么编码。hevc = 解密后原样封装、不重编码，约 1 秒出片且画质是源站原画（仅 iOS / Android / macOS / 部分桌面 Chrome 能解）；h264 = 重编码，兼容所有浏览器但要等数十秒。浏览器解不了 HEVC 时选 hevc 会只有声音没有画面，所以本页会在能解时自动选 hevc、不能解时保持自动。

选填：本站直出时怎么把数据发给客户端。pipe（默认）= 边解密（必要时边转码）边发分片流，实测首块 0.3 秒、浏览器首帧 1.5 秒；这一遍转完会把整集留成缓存产物，之后同一地址就是标准文件出流（可拖动、可续播）。首次响应本身没有 Content-Length、不能拖动。file = 先在服务端生成整集文件再整文件出流，首次要等（hevc 约 1 秒、h264 数十秒），但从第一次起就能拖动。iOS 原生播放器 / 部分小程序播放器对分片流兼容性不佳时改传 file。

  • 源站有公开 mp4 的集默认返回源站明文直链（origin，源站仅 360p）；调用方指定了更高画质（q 高于源站）或该集源站无公开 mp4 时，改由本站出流（stream）。data.source 区分来源（取值与「剧集详情」的 episodes[].source 一致）：
  • · origin —— 源站明文直链（源站公开 mp4，仅 360p）；
  • · stream —— 本站直出：data.url 为可直接交给 <video> 播放的地址（支持 HTTP Range 拖动），画质见 data.quality、编码见 data.codec，data.ready=false 表示该画质首次被点播、服务端正在生成（hevc 约 1 秒内即可 ready=true；h264 需数十秒），请轮询该地址：202=正在生成、503=生成失败（响应体里有原因）、200/206=可播放，别只按 HTTP 200 判定。触发后台生成的是该地址本身的第一次请求（GET 或 HEAD）—— 只反复调用播放接口不会开始生成。
  • data.stream_mode 说明这条地址怎么出流：pipe（默认）= 服务端边解密边发分片流，请求即播（实测首块 0.3 秒、浏览器首帧 1.5 秒）；首次响应没有 Content-Length、不能拖进度条，但这一遍转完会把整集留成缓存产物，此后同一地址再请求即变成 file 出流（可拖动、可续播）；file = 产物已就绪（或显式传 mode=file），整文件出流、支持 HTTP Range。播放器可按 data.stream_mode 决定是否显示拖动条。
  • 该地址的鉴权由 data.url 里的时效令牌承担（默认 2 小时），过期后重新调用本接口换取新地址。
  • ep 越界（超出总集数）返回 PARAM_VALUE_INVALID。
  • 源站直链带时效，请勿长期缓存。
响应说明 外层统一格式
字段 类型 说明
series_id string 剧集 ID（回带入参）
ep int 集号（回带入参）
playable bool 是否可播（成功恒为 true）
source string 来源：origin 源站直链 / stream 本站直出
url string 播放地址（带时效）
url_type string 仅 source=stream：地址类型（mp4）
quality int 仅 source=stream：出流画质（宽度上限）
codec string 仅 source=stream：产物编码（h264 / hevc）
ready bool 仅 source=stream：产物是否已生成（false 需轮询）
stream_mode string 仅 source=stream：出流方式 pipe 边解密边发（不可拖动）/ file 整文件（可拖动）
episode_id string 仅 source=origin：源站集 ID
duration int 仅 source=origin：时长
width int 仅 source=origin：视频宽
height int 仅 source=origin：视频高
poster string 仅 source=origin：封面图地址
返回示例 
{
  "series_id": "7686894628578020414",
  "ep": 1,
  "episode_id": "123",
  "playable": true,
  "url": "https://www.hongguoduanju.com/xxx.mp4",
  "duration": 90000,
  "width": 720,
  "height": 1280,
  "poster": "https://img.example.com/1.jpg",
  "source": "origin"
}
在线播放测试 hls.js / mp4 发送上方请求成功后自动加载播放；也可直接粘贴任意播放地址（m3u8 / mp4）测试。
GET /api/dramas/hongguo/stream 累计调用 112 次

网页直出流

第 4 集及以后的「网页可播」流地址（普通 <video> 标签直接播放）。

必填：由「播放地址」接口下发的时效令牌，无需项目签名。

  • 该地址由「播放地址」接口返回，供 <video> 标签直接播放，不带项目签名（浏览器加不了签名），鉴权用 URL 里的时效令牌。
  • 画质与编码都由「播放地址」的参数决定、已写在令牌里，本端点不需要再传 —— 同一集不同画质/编码是不同的地址，各自独立缓存（hevc 产物在 &lt;画质&gt;/hevc/ 子目录，h264 在同档目录下）。
  • 出流有两种形态，按 data.stream_mode 区分：pipe = 服务端边解密（必要时边转码）边发分片流，请求即开始返回数据（实测首块 0.3 秒），这一遍响应无 Content-Length、不支持 Range（不能拖进度条），但转完会自动留成产物；file = 产物已就绪，整文件出流并支持 Range（206）拖动。因此「第一次点播不能拖、第二次起可以」是正常现象。
  • pipe 模式下同时在播的人数有上限，满了返回 503 + Retry-After（地址仍然有效，稍后重试即可，不必重新调播放接口）。
  • 仅在 HONGGUO_STREAM_MODE=file 时才会出现「首次点播返回 202（Retry-After: 3），服务端后台生成」的老流程；生成失败返回 503（响应体里有失败原因）。请勿只按 HTTP 200 判定。
  • 令牌无效或过期返回 403，需重新调用「播放地址」接口获取新地址。
响应说明 外层统一格式

成功返回视频二进制流（video/mp4；pipe 模式为分片流、file 模式支持 Range）；file 模式下生成中返回 202、生成失败或管道并发已满返回 503、令牌无效或过期 403，均非统一 JSON 信封。

短剧 API 常见问题

短剧 API 是什么？能做什么？
短剧服务把短剧站的公开数据封装成 7 个接口：榜单、分类清单、分类列表、搜索、剧集详情、播放地址与网页直出流。按「榜单 / 分类 → 列表 → 搜索 → 详情 → 播放」的顺序调用，就能搭起一个短剧网站、短剧小程序或短剧 H5。
支持哪些短剧平台？有红果短剧接口吗？
目前提供红果短剧（红果免费短剧）线路 /api/dramas/hongguo/，封面、简介、演员、集数、分类与榜单都取自源站实时数据；其它短剧平台会按同一套端点结构扩展，接入方代码不用改。
能直接拿到可播放的地址（m3u8 / mp4 直链）吗？
能。play 端点返回当前集的可播地址：第 1~3 集是源站明文直链（源站只有 360p）；第 4 集及以后源站只下发 DRM 加密的 H.265，由本服务在服务端解密后中转出流，返回的地址带时效令牌，直接交给 <video> 或播放器即可。
网页（H5）能直接播放吗？必须装 App 吗？
不用装 App。多数浏览器解不了 H.265，所以第 4 集及以后由服务端转成 H.264 再出流（stream 端点），实测首帧约 1~2 秒；App 内想保留原画质可以走 play 拿到的直链。
支持按剧名搜索短剧吗？
支持。/api/dramas/hongguo/search 按剧名关键词搜索；批量取剧用榜单 /api/dramas/hongguo/rank 或分类列表 /api/dramas/hongguo/list，分类树为 4 个一级 + 40 个二级题材。
画质可以选吗？最高多少？
可以。play / stream 的 q 参数按输出宽度选 360 / 480 / 540 / 720 / 1080，默认 1080（源站最高档，不再二次缩放）。
短剧接口怎么接入？需要什么鉴权？
它属于需签名的服务：申请接入项目后，用 app_id + timestamp + nonce + sign（HMAC-SHA256）调用。不想自己拼签名的话，本页右侧「在线调试」可以代签并直接发请求。
数据是实时的吗？会有缓存吗？
源站数据实时爬取并做短时缓存（默认 120 秒），榜单与详情基本秒级返回；播放地址带有效期，过期后重新调用 play 取新地址即可。
小影API · 通用 API 聚合服务