小影API 小影API

Short Dramas

Short-drama service: rankings, categories, search, details and playback URLs — follow ranking / category → list → details → playback to build a short-drama site.

/api/dramas/

Service Description

The short-drama service aggregates data from short-drama sites and provides rankings, categories, search, details and playback URLs. Follow ranking / category → list → details → playback to stand up a short-drama site; the search endpoint looks series up by title keyword.

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

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

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

Direct source links returned by the playback endpoint are MP4 and time-limited — do not cache them on the client. Series metadata and episode lists are cached longer; playback links are cached briefly so they stay fresh. This service requires project signature.

Response Format

Every endpoint returns the same JSON envelope; the payload is always inside data: 

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}
  • code: business status code. 10000 means success; anything else is an error — see the Error Codes page for the full list.
  • msg: a human-readable message you can show to end users, but never use it for program logic.
  • data: the payload; usually null on error. Each endpoint's Response section lists its data fields.

Judge success by code, not by the HTTP status code. View all error codes

Hongguo Short Dramas

Hongguo Short Dramas (hongguoduanju.com) website Signature Required

Crawls the source site's SSR data in real time and caches it. Series metadata / episode lists are cached longer; playback links are cached briefly.

GET /api/dramas/hongguo/rank Total calls: 8

Rankings

Get short-drama rankings — hot, live-action hot, AI-drama hot and comic-drama hot — with pagination.

Optional: ranking type, defaults to hot-drama.

Optional: page number, starting from 1, default 1.

  • Returns PARAM_VALUE_INVALID when the ranking type is invalid.
  • data is the ranked series list (fields match the category list endpoint).
Response Common envelope
Field Type Description
type string Ranking type (echoes the input)
page int Current page
total_page int Total pages
results array Ranking drama list
results[].rank int Rank
results[].series_id string Series ID, pass to the detail/play API
results[].name string Drama title
results[].cover string Cover image URL
results[].url string Detail page URL
results[].heat string Popularity (null if none)
results[].score string Rating (null if none)
results[].favorite string Favorites count (null if none)
results[].like string Likes count (null if none)
results[].tags array Genre tags
results[].intro string Synopsis
Example response 
{
  "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 Total calls: 1

Category List

Get the category tree (top level -> sub-genres).

  • Categories have two levels: the top level is the content form (live-action drama / comic drama / AI drama / comics) and the second level is the genre (romance / period / comeback ...).
  • Every node's slug can be passed straight to the category parameter of the category list endpoint: a top-level slug returns that whole top level, while a sub-genre returns only that genre (e.g. real-drama/romance). Top levels with no sub-genres (comics) have an empty children array.
Response Common envelope
Field Type Description
categories array Category tree (top level)
categories[].slug string Top-level slug, pass to the list API as category
categories[].name string Top-level category name
categories[].url string Category page URL
categories[].children array Second-level genres (empty array if none)
categories[].children[].slug string Second-level slug (top/second form)
categories[].children[].name string Second-level genre name
categories[].children[].url string Category page URL
Example response 
{
  "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 Total calls: 4

Category List

Get a short-drama list by category, with pagination.

Required: the category — a top-level slug (e.g. real-drama) or "top-level/sub" (e.g. real-drama/romance); see the category list endpoint for the full set.

Optional: page number, starting from 1, default 1.

  • Returns PARAM_MISSING / PARAM_VALUE_INVALID when category is missing or invalid.
Response Common envelope
Field Type Description
category string Category slug (echoes the input)
page int Current page
results array Drama list
results[].series_id string Series ID, pass to the detail/play API
results[].name string Drama title
results[].cover string Cover image URL
results[].url string Detail page URL
results[].tags array Genre tags
results[].intro string Synopsis
results[].rank null Ranking-only field, always null in the list API
results[].heat null Ranking-only field, always null in the list API
results[].score null Ranking-only field, always null in the list API
results[].favorite null Ranking-only field, always null in the list API
results[].like null Ranking-only field, always null in the list API
pagination object Pagination
pagination.current int Current page
pagination.total int Total pages
Example response 
{
  "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 Total calls: 80

Series Details

Get series details and the full episode list.

Required: series ID (from list / search results).

  • data.episodes is the full episode list; each item has ep / episode_id / playable / source.
  • episodes[].playable follows exactly the same rule as the playback endpoint: an episode is playable when either route works — the source link or this site's own stream. source says which one applies: origin (source link) / stream (site stream; the first play takes tens of seconds to generate). Site streaming is available by default, so episode 4 and later are usually playable=true too.
  • data.playable_cnt is the unbroken range of source links (the first N episodes, meaning unchanged); data.listed_cnt is how many episodes are actually playable (the count of playable=true). To tell whether a specific episode plays, use episodes[].playable — do not derive it from playable_cnt.
  • Returns EXTERNAL_API_FAILED when the series does not exist.
Response Common envelope
Field Type Description
series_id string Series ID (echoes the input)
name string Drama title
cover string Cover image URL
intro string Synopsis
tags array Genre tags
episode_cnt int Total episodes
playable_cnt int Contiguous playable episodes from the upstream direct link
listed_cnt int Actual playable episode count (playable=true)
episodes array Full episode list
episodes[].ep int Episode number (starting from 1)
episodes[].episode_id string Upstream episode ID
episodes[].playable bool Whether this episode is playable
episodes[].source string Source: origin (upstream direct link) / stream (served by this site)
Example response 
{
  "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 Total calls: 320

Playback URL

Get the playback URL of an episode (directly playable in a browser).

Required: episode number, starting from 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 决定是否显示拖动条。
  • That URL is authenticated by the time-limited token it carries (2 hours by default); call this endpoint again for a fresh URL after it expires.
  • Returns PARAM_VALUE_INVALID when ep is out of range (beyond the total episode count).
  • Direct source links are time-limited — do not cache them long-term.
Response Common envelope
Field Type Description
series_id string Series ID (echoes the input)
ep int Episode number (echoes the input)
playable bool Whether playable (always true on success)
source string Source: origin (upstream direct link) / stream (served by this site)
url string Play URL (time-limited)
url_type string Only source=stream: URL type (mp4)
quality int Only source=stream: output quality (max width)
codec string 仅 source=stream：产物编码（h264 / hevc）
ready bool Only source=stream: whether the output is ready (poll while false)
stream_mode string 仅 source=stream：出流方式 pipe 边解密边发（不可拖动）/ file 整文件（可拖动）
episode_id string Only source=origin: upstream episode ID
duration int Only source=origin: duration
width int Only source=origin: video width
height int Only source=origin: video height
poster string Only source=origin: poster image URL
Example response 
{
  "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"
}
Playback Test hls.js / mp4 Plays automatically after the request above succeeds; you can also paste any playback URL (m3u8 / mp4) to test.
GET /api/dramas/hongguo/stream Total calls: 320

Web Direct Stream

The web-playable stream URL for episode 4 and later (plays directly in a plain <video> tag).

Required: the time-limited token issued by the playback endpoint; no project signature needed.

  • This URL is returned by the playback endpoint and plays directly in a <video> tag. It carries no project signature (browsers cannot add one); authentication uses the time-limited token in the 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 判定。
  • An invalid or expired token returns 403; call the playback endpoint again for a fresh URL.
Response Common envelope

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

XiaoYingAPI · Unified API Aggregation Service