小影API 小影API

短劇

短劇服務：提供短劇的榜單、分類、搜索、詳情與播放直鏈能力，按「榜單/分類 → 列表 → 詳情 → 播放」流程即可搭建短劇站。

/api/dramas/

服務說明

短劇服務聚合短劇站數據，提供榜單、分類、搜索、詳情與播放直鏈等能力，按「榜單/分類 → 列表 → 詳情 → 播放」的順序即可搭起一個短劇站，搜索接口則支持按劇名關鍵詞查劇。

播放能力：前 3 集由源站直接下發明文直鏈；第 4 集及以後源站只下發 DRM 加密的H.265（瀏覽器無法直接解碼），由本服務在服務端解密並轉成 H.264 後出流，播放接口返回的地址可直接交給瀏覽器的「視頻」標籤播放，支持拖動進度條。第 4 集及以後首次點播需等待數十秒生成，之後即刻返回。

播放接口返回的源站直鏈為 MP4 且帶時效，請勿在客戶端長期緩存；劇集元數據與集列表緩存較久，播放直鏈緩存較短以便及時刷新。本服務需項目簽名。

紅果短劇

紅果短劇（hongguoduanju.com）網頁版 需簽名

實時爬取源站 SSR 數據並緩存。劇集元數據/集列表緩存較久；播放直鏈緩存較短。

GET /api/dramas/hongguo/rank 累計調用 0 次

榜單

獲取短劇榜單，支持熱播榜 / 真人劇熱播榜 / AI劇熱播榜 / 漫劇熱播榜與分頁。

可選：榜單類型，默認 hot-drama（熱播榜）。

可選：頁碼，從 1 開始，默認 1。

  • 榜單類型非法時返回 PARAM_VALUE_INVALID。
  • 返回 data 為榜單劇集列表（字段與「分類列表」接口一致）。
GET /api/dramas/hongguo/categories 累計調用 2 次

分類清單

獲取分類樹（一級 -> 二級題材）。

  • 分類是兩級的：一級是內容形態（真人劇 / 漫劇 / AI劇 / 漫畫），二級是題材（愛情 / 年代 / 逆襲 …）。
  • 每個節點的 slug 都可直接傳給「分類列表」接口的 category：一級取該一級全部，二級只取該題材（形如 real-drama/romance）；無二級的一級（漫畫）children 為空數組。
GET /api/dramas/hongguo/list 累計調用 3 次

分類列表

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

必填：分類取值 —— 一級 slug（如 real-drama）或「一級/二級」（如 real-drama/romance），完整取值見「分類清單」接口。

可選：頁碼，從 1 開始，默認 1。

  • category 缺失或非法時返回 PARAM_MISSING / PARAM_VALUE_INVALID。
GET /api/dramas/hongguo/detail 累計調用 4 次

劇集詳情

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

必填：劇集 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調用失敗）。
GET /api/dramas/hongguo/play 累計調用 7 次

播放地址

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

必填：集數，從 1 開始。

選填：本站直出的畫質，取值是輸出寬度上限（短劇是豎屏，1080 即 1080×1920，也就是日常說的 1080p）。每檔產物各存一份；換畫質要重新調本接口換地址。

  • 前 3 集返回源站明文 MP4 直鏈；第 4 集及以後源站只下發 DRM 加密的 H.265（瀏覽器無法解碼），改由本站出流。data.source 區分來源（取值與「劇集詳情」的 episodes[].source 一致）：
  • · origin —— 源站明文直鏈（前若干集）；
  • · stream —— 本站直出：data.url 為可直接交給 <video> 播放的地址（明文 H.264、支持 HTTP Range 拖動），畫質見 data.quality，data.ready=false 表示該畫質首次被點播、服務端正在生成（約數十秒），請輪詢該地址：202=正在生成、503=生成失敗（響應體裡有原因）、200/206=可播放，別只按 HTTP 200 判定。
  • 該地址的鑑權由 data.url 裡的時效令牌承擔（默認 2 小時），過期後重新調用本接口換取新地址。
  • ep 越界（超出總集數）返回 PARAM_VALUE_INVALID。
  • 源站直鏈帶時效，請勿長期緩存。
在線播放測試 hls.js / mp4 發送上方請求成功後自動加載播放；也可直接粘貼任意播放地址（m3u8 / mp4）測試。
GET /api/dramas/hongguo/stream 累計調用 87 次

網頁直出流

第 4 集及以後的「網頁可播」流地址（普通 <video> 標籤直接播放）。

必填：由「播放地址」接口下發的時效令牌，無需項目簽名。

  • 該地址由「播放地址」接口返回，供 <video> 標籤直接播放，不帶項目簽名（瀏覽器加不了簽名），鑑權用 URL 裡的時效令牌。
  • 畫質由「播放地址」的 q 參數決定、已寫在令牌裡，本端點不需要再傳 —— 同一集不同畫質是不同的地址，各自獨立緩存。
  • 支持 HTTP Range（206）：可拖動進度條、可斷點續傳。
  • 首次點播該集的某一畫質時返回 202（Retry-After: 3），服務端在後臺解密並轉成 H.264（約數十秒），200 / 206 才是可播放；生成失敗返回 503（響應體裡有失敗原因），請勿只按 HTTP 200 判定。產物落盤永久復用，此後再播為即刻返回。
  • 令牌無效或過期返回 403，需重新調用「播放地址」接口獲取新地址。
小影API · 通用 API 聚合服務