小影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 累計調用 16 次

榜單

獲取短劇榜單，支持熱播榜 / 真人劇熱播榜 / 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 累計調用 2 次

分類列表

按分類獲取短劇列表，支持分頁。

必填：分類取值 —— 一級 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 累計調用 128 次

劇集詳情

獲取劇集詳情與全量集列表。

必填：劇集 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 累計調用 7475 次

播放地址

獲取指定集的播放地址（網頁可直接播放）。

必填：集數，從 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 累計調用 7478 次

網頁直出流

第 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 聚合服務