如果你需要在脚本、工作流或 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 参数 | 单集价格 | 特色能力 |
|---|---|---|---|
| 红果短剧 | hg | 0.01 U / 集 | 支持分享链接、口令、剧集 ID、剧名搜剧 |
| PineDrama | pinedrama | 0.01 U / 集 | 中英文搜剧,支持中/英/西三语字幕导出 |
| ReelShort | reelshort | 720P 0.01 U · 1080P 0.02 U | 双画质任选,原站会员集同样可下(无字幕) |
四、防误扣费与安全护栏
自动化场景最怕 Agent 未经确认自己花钱。hgc link 在非交互环境下必须显式传入 --yes(API 需传 confirm: true),否则以退出码 3 返回本次精确报价,不触发扣费。
此外,API Key 支持按权限细分(read / jobs / links),单账号最多建 5 把 Key,泄露后在 /agent 页面一键撤销立即失效;下载失败的集不计费,同一任务的直链 24 小时过期后重新执行取链也不会重复扣款。