教程 · API 与 CLI

红果短剧 API 与命令行批量下载指南

红果API(hongguoapi.com)提供标准 REST API 与 hgc 命令行工具,支持红果短剧、PineDrama、ReelShort 搜索解析、异步下单、进度查询与直链提取,可直接接入 Claude Code 与 Codex。

如果你需要在脚本、工作流或 AI Agent(Claude Code / Codex)里自动完成短剧检索与批量下载,不需要在浏览器里逐个点击。红果API(hongguoapi.com)提供与网页同源同价的 REST API 与 hgc CLI:四步完成 search → submit → status → link,按成功交付的集数计费(0.01 U/集起),取链时才扣费。

一、标准接口清单(REST API)

所有业务接口统一挂在 https://hongguoapi.com/api/v1/agent,使用 Authorization: Bearer hgc_live_… 鉴权,限流 120 次/分钟,余额与网页账号共用:

方法与路径作用计费与约束
GET /manifest获取版本、支持平台与限额清单公开免登录
GET /search?q=关键词按剧名搜剧,支持 source=hg|pinedrama|reelshort免费;海外源搜到即入库
POST /jobs提交下载任务(传 series_id 或分享链接 + 集数范围)排队不扣费,返回报价
GET /jobs/{id}查询下载进度、失败集与预估剩余时间免费轮询
POST /jobs/{id}/links提取分集直链或 ZIP 整包直链(需 confirm: true)取件才扣费;重复取幂等

二、一条命令接入 Claude Code / Codex(hgc CLI)

不想手写 HTTP 轮询逻辑,可以直接安装官方单文件命令行工具 hgc。在 /agent 页面生成 API Key 后,安装命令会自动写入 CLI、凭证与 Agent 指令段:

  • 搜剧:hgc search "闪婚" --json(加 --global 搜 PineDrama,--reelshort 搜 ReelShort);
  • 下单:hgc submit <id|链接> --episodes 1-20 --json(ReelShort 用 --quality 720|1080);
  • 等待:hgc status <job_id> --watch 阻塞直到任务完成;
  • 取链:hgc link <job_id> --yes --zip --json 输出 24 小时有效直链。

三、三平台能力与接口计费对照

平台source 参数单集价格特色能力
红果短剧hg0.01 U / 集支持分享链接、口令、剧集 ID、剧名搜剧
PineDramapinedrama0.01 U / 集中英文搜剧,支持中/英/西三语字幕导出
ReelShortreelshort720P 0.01 U · 1080P 0.02 U双画质任选,原站会员集同样可下(无字幕)

四、防误扣费与安全护栏

自动化场景最怕 Agent 未经确认自己花钱。hgc link 在非交互环境下必须显式传入 --yes(API 需传 confirm: true),否则以退出码 3 返回本次精确报价,不触发扣费。

此外,API Key 支持按权限细分(read / jobs / links),单账号最多建 5 把 Key,泄露后在 /agent 页面一键撤销立即失效;下载失败的集不计费,同一任务的直链 24 小时过期后重新执行取链也不会重复扣款。

常见问题

红果短剧 API 怎么计费,调用搜索和解析要钱吗?

搜索、解析、建任务和查进度全部免费,只有在任务完成并调用 /links 取件时才按成功交付的集数计费(红果与 PineDrama 0.01 U/集,ReelShort 720P 0.01 U / 1080P 0.02 U),失败集不计费。

没有编程基础能用 CLI / Agent 自动搬剧吗?

可以。在 /agent 页面生成密钥后复制一行安装命令贴进终端,之后在 Claude Code 或 Codex 里直接用自然语言说「帮我搜某部剧并下前 20 集」即可。

海外剧(PineDrama / ReelShort)也能通过同一套 API 下载吗?

可以。同一个 API Key 通用三个平台,只需在 search 与 submit 时指定 source=pinedrama 或 source=reelshort(PineDrama 需先 search 入库再 submit)。

想私有化部署整套短剧解析与下载 API 怎么办?

站点提供完整的 FastAPI + React + 下载 Worker 源码一次性买断授权,含自部署手册与双通道支付回调,可在源码授权页(/source)查看详情。

接着看

按使用场景拆成专题,各讲一件事

想看具体某部剧的集数与体积,去 短剧片库;想知道最近大家在追什么,看 热搜短剧榜;需要英文海外指南,见 Online Short Drama Downloader。