API 开发文档RED FRUIT OPEN API
在线试用 返回首页
API Reference · v1

短剧聚合接口文档

覆盖红果原生接口与 9 个内容通道。搜索、推荐、上新、筛选、排行、详情公开调用;只有返回播放或下载地址的解析接口需要接口密钥。

https://orz.buaile.cn/api/api.php

快速开始

推荐按“搜索作品 → 获取分集 → 解析视频”三步调用。

1
搜索或获取上新

公开接口,得到作品 book_id

2
读取详情与分集

公开接口,得到每集 video_id

3
解析播放地址

携带 apiKey,得到 MP4 或 HLS 地址。

请求约定

项目约定
协议与方法生产环境使用 HTTPS;当前接口均支持 GET,请求参数使用 UTF-8 URL 编码。
响应格式application/json; charset=utf-8,成功通常为 code=200
业务状态必须读取 JSON 的 code,不要只判断 HTTP 状态;部分业务错误仍可能由网关以 HTTP 200 返回。
分页page 从 1 开始;统一通道的 page_size 默认 20,范围 1~50。
缓存缓存由后端管理。公开调用方不要传 freshforce_refreshno_cache 绕过缓存。
视频 ID必须使用详情接口返回的原始值。部分通道使用字母、冒号或复合 ID,不能强制转成整数。
接口密钥一次开通全部可用通道:后台关闭的通道会返回 CHANNEL_DISABLED,关闭后不会继续对外展示或调用。

鉴权方式

查询元数据无需密钥;视频解析必须使用 api- 开头的接口密钥。

公开接口(无需密钥)

search、recommend、latest、filters、rank、bookid/detail。

受保护接口(需要密钥)

video_id/play、video_ids/play_batch、play_all。

支持的三种写法

Query 参数(推荐快速测试)
GET https://orz.buaile.cn/api/api.php?type=video_id&video_id=VIDEO_ID&apiKey=api-YOUR_INTERFACE_KEY
X-API-Key 请求头(推荐服务端使用)
curl -L -H "X-API-Key: api-YOUR_INTERFACE_KEY" \
  "https://orz.buaile.cn/api/api.php?type=video_id&video_id=VIDEO_ID&level=1080p&fast=1"
Authorization 请求头
Authorization: Bearer api-YOUR_INTERFACE_KEY# 同时支持:Authorization: ApiKey api-YOUR_INTERFACE_KEY
不要使用旧参数:api_key=...key=... 被视为旧软件下载密钥入口,会明确拒绝。接口租用版只使用 apiKeyX-API-KeyAuthorization
密钥安全:不要把接口密钥写进网页前端、公开仓库或分享截图。推荐由自己的服务端保存密钥并代理视频解析请求。

通道代码与真实能力

“公开”表示无需密钥;“解析”表示需要有效接口密钥。以此表为准。

编号 / 通道channel公开动作需密钥动作通道差异
通道1 · 红果 hongguo search、latest、rank、detail play、play_batch 使用红果原生路由;整剧应先取详情,再批量解析 video_ids。
通道2 · 小红书 xiaohongshu search、recommend、rank、detail play、play_all、play_batch 部分翻页使用 cursor;播放可带 session_id、cursor_score。
通道3 · 拼多多 pdd search、recommend、latest、filters、rank、detail play、play_all、play_batch video_id 可能是 topic_id:feed_id;play_all 偏向返回分集,下载建议 detail + play_batch。
通道4 · 追番社 zhuifanshe search、recommend、latest、rank、detail play、play_all、play_batch 推荐支持 sort=default/latest/hot。
通道5 · 得间 dejian search、recommend、filters、rank、detail play、play_all、play_batch 搜索可传 scan_pages;播放可传 codec=h264/h265。
通道6 · 河马 hema search、recommend、latest、filters、rank、detail play、play_batch detail 必须同时传 book_id 与 episode_cnt;不支持 play_all。
通道7 · 麦萌/汤圆 maimeng search、recommend、latest、filters、rank、detail play、play_all、play_batch play_all 可传 concurrency=2~12;后端自动使用服务器凭证。
通道8 · 围观 weiguan search、recommend、latest、filters、rank、detail play、play_all、play_batch filters 返回 audience、subject/tag、order 等可选值。
通道9 · 喜番 xifan search、recommend、latest、filters、rank、detail play、play_all、play_batch 可能返回 m3u8/HLS 地址;下载方需按 HLS 方式合并为 MP4。

统一动作别名

标准动作可接受的 type/action 别名主要返回
recommendhome、featured推荐列表
latestdays_7_to_date、today_new、new、new_drama最新列表
detailbookid、episodes、collection作品信息和分集 video_id
playvideo_id、play_info、video单集播放/下载地址
play_batchvideo_ids、batch_play最多 50 个 video_id 的解析结果
play_allvideo_all、episode_all通道支持时返回整剧结果
filterscatalog、categories筛选项
rankranking、rankings排行榜

红果原生接口

红果保留原来的高性能路由,不需要传 channel;元数据公开,只有视频地址解析需要密钥。

GET?name=关键词&tab_type=11&page=1公开

搜索短剧或漫剧,每页最多 30 条。

参数必填类型 / 默认值说明
namestring搜索关键词,必须 URL 编码。
tab_typeint / 1111 短剧,19 漫剧。
pageint / 1从 1 开始,后续页 offset 每次增加 30。
请求示例
GET?type=days_7_to_date&action=today_new公开

获取当天上新。默认按 Asia/Shanghai 当天判断并由后端缓存,今日模式返回当天完整结果。

参数必填类型 / 默认值说明
typedays_7_to_date固定值。
actionstringtoday_new 短剧;mj_today_new 漫剧;aiju_today_new AI 真人剧。
all_timebool / falsetrue 时切换到全部时间分页模式,每页 20 条。
pageint / 1主要用于 all_time 模式。
fastbool / false优先快速返回同配置缓存;后端可能异步刷新。
page_sizeint / 30fast 模式首屏条数,最大 100。
min_duration秒数或文本过滤最小时长;duration_1h=1 是至少 1 小时的快捷写法。
max_duration秒数或文本过滤最大时长。
vertical / horizontalbool二选一,筛选竖屏或横屏作品。
GET?type=rank&selected_items=ranklist_hot_sc&page=1公开

获取红果排行榜。第一次可使用默认值,再从响应中的 selector_item_id 获取其它榜单值。

参数必填说明
type固定 rank
selected_items默认 ranklist_hot_sc
page页码,从 1 开始。
请求示例
https://orz.buaile.cn/api/api.php?type=rank&selected_items=ranklist_hot_sc&page=1
GET?type=bookid&book_id=BOOK_ID公开

获取作品信息和全部分集。后续解析必须使用 data[].video_id

参数必填说明
type固定 bookid
book_id搜索、上新或排行返回的作品 ID。
请求示例
https://orz.buaile.cn/api/api.php?type=bookid&book_id=7626291792958213182
GET?type=video_id&video_id=VIDEO_ID&level=1080p&fast=1&apiKey=api-...需密钥

解析一个红果视频地址。成功后顶层 url 可直接使用。

参数必填类型 / 默认值说明
typevideo_id固定值。
video_id数字字符串来自 bookid 接口的单集 ID。
level1080p支持 360p/480p/540p/720p/1080p/1440p/2160p/all;无对应档位时后端选择可用流。
fast01 只返回精简信息;0 返回画质、码率、尺寸等详细信息。
apiKeyapi-...也可改用请求头鉴权。
请求示例
https://orz.buaile.cn/api/api.php?type=video_id&video_id=7625142218017229849&level=1080p&fast=1&apiKey=api-YOUR_INTERFACE_KEY
GET?type=video_ids&video_ids=ID1,ID2&level=1080p&apiKey=api-...需密钥

一次解析 1~50 个不重复的视频 ID。仅成功项计费,失败项会自动退款;有效会员返回 points_used=0

参数必填说明
video_ids英文逗号分隔,最多 50 个。
detail1 时每个结果附带更详细的原始解析数据。
level / fast / apiKey同单集含义与单集解析一致。
请求示例
https://orz.buaile.cn/api/api.php?type=video_ids&video_ids=7618120805276191806,7618120703685971006&level=1080p&fast=1&apiKey=api-YOUR_INTERFACE_KEY

统一通道接口

通道 2~9 使用同一套路由和标准动作;红果请优先使用上面的原生路由。

统一格式:https://orz.buaile.cn/api/api.php?channel=通道代码&type=动作&其它参数
GET?channel=pdd&type=search&name=关键词&page=1&page_size=20公开

搜索指定通道。namekeyword 等价,只要带关键词就会自动识别为 search。

参数必填说明
channel通道代码或数字 2~9。
type建议固定 search
name搜索关键词。
page默认 1。
page_size默认 20,最大 50。
请求示例
GET?channel=CODE&type=recommend|latest|filters|rank公开

获取推荐、最新、筛选目录或排行。先查看“通道能力”表,未支持的动作返回 422。

动作通用参数常用附加参数
recommendpage、page_size追番社:sort;小红书/河马:cursor。
latestpage、page_size只有能力表标记 latest 的通道可用。
filters先请求 filters,再把返回值用于 search/rank。
rankpage、page_sizerank_type 或 selected_items;围观 rank_type 支持 1/7/2/5/3/6。
GET?channel=CODE&type=bookid&book_id=BOOK_ID公开

获取作品详情和分集,推荐读取 normalized_data。河马通道必须额外传列表返回的 episode_cnt

参数必填说明
channel通道代码。
book_id搜索/推荐列表返回的作品 ID。
episode_cnt河马必填河马用于生成分集 ID;最大按 300 集处理。
page_size小红书等通道用于详情分页。
请求示例
https://orz.buaile.cn/api/api.php?channel=pdd&type=bookid&book_id=BOOK_ID
GET?channel=CODE&type=video_id&video_id=VIDEO_ID&apiKey=api-...需密钥

解析单集。请把详情接口返回的 video_id 原样传入,不要自行拆分复合 ID。

参数必填说明
channel必须和该 video_id 的来源通道一致。
video_id允许字母、数字、下划线、点、冒号和连字符,最长 160 字符。
book_id部分通道上游解析需要作品上下文时一并传入。
level默认 1080p;上游不提供时可能自动降级。
apiKey或使用鉴权请求头。
请求示例
https://orz.buaile.cn/api/api.php?channel=pdd&type=video_id&video_id=VIDEO_ID&level=1080p&fast=1&apiKey=api-YOUR_INTERFACE_KEY
GET?channel=CODE&type=video_ids|play_all&...&apiKey=api-...需密钥

video_ids 批量解析最多 50 个 ID;play_all 按 book_id 获取整剧,河马不支持。

动作必要参数建议
video_idsvideo_ids=ID1,ID2跨通道不能混传;每次请求只能属于一个 channel。
play_allbook_id=BOOK_ID麦萌可传 concurrency=2~12;若通道整剧返回不完整,改用 detail + video_ids。
整剧请求示例
https://orz.buaile.cn/api/api.php?channel=pdd&type=play_all&book_id=BOOK_ID&level=1080p&apiKey=api-YOUR_INTERFACE_KEY

通道特殊参数速查

通道参数用途
小红书cursorsession_idcursor_score推荐/详情翻页和播放上下文。
拼多多topic_idfeed_id通常已编码进 topic_id:feed_id 形式的 video_id。
追番社sort=default|latest|hotepisode推荐排序和单集上下文。
得间scan_pagesallstart_idend_idcodec搜索扫描、详情范围与编解码偏好。
河马cursortag_idssearch_sourceepisode_cnt列表翻页、筛选来源和生成分集。
麦萌rank_typeconcurrency榜单类型和整剧解析并发(2~12)。
围观audiencesubject/tagshort_play_typeorderrank_type先调用 filters 获取可用值。
喜番featuredsubjectaudienceepisode_rangerank_type筛选和榜单;可能返回 m3u8。

返回结构与字段字典

红果原生结构稳定;统一通道同时返回上游 data 和标准化 normalized_data。

推荐读取顺序:统一通道列表优先读 normalized_data;视频 URL 优先读顶层或项目内的 url,并兼容 play_url / video_url / download_url / resource_url

通用响应字段

code
业务状态码。200 成功;其它值按错误码表处理。
msg
中文状态说明,可用于日志,不建议依靠文本做程序判断。
data
红果或上游原始数据。不同通道字段可能不同,用于获取通道特有字段。
normalized_data
统一通道标准化数组,适合跨通道客户端直接消费。
channel / channel_no / channel_name
通道代码、编号和显示名称。
channel_action
规范化后的动作,如 search、detail、play。
result_count / total
本次标准化条数与上游总数;上游未提供 total 时等于当前条数。
page / page_size
分页信息。游标型上游还可能在 data 中返回 cursor。
billing_type
interface_vip、interface_points 等结算方式,仅解析接口返回。
points_used / remaining_points
本次成功解析所用积分和剩余积分;会员通常 points_used 为 0。

normalized_data 单项字段

字段含义备注
book_id作品 ID用于 detail/play_all。
video_id分集 ID用于 play/play_batch,必须当字符串保存。
title / book_name作品或分集标题至少读取其中一个。
cover_url / cover封面统一通道优先 cover_url。
author作者/版权方上游没有时可能为空。
intro / desc简介上游没有时可能为空。
type / category题材分类可能是文本或多个标签拼接。
episode_cnt总集数部分列表只返回更新集数。
play_cnt热度/播放量可能是数字或“xx万播放”文本。
publish_time上线/更新时间格式通常为 YYYY-MM-DD HH:mm:ss。
duration时长可能是文本、秒或毫秒,取决于上游。
url播放/下载地址可能是 MP4,也可能是 m3u8/HLS。
channel / source来源通道切换通道后用于防止 ID 串线。

搜索响应

{
    "code": 200,
    "msg": "搜索成功",
    "data": [
        {
            "book_id": "7626291792958213182",
            "title": "示例短剧",
            "author": "版权方",
            "type": "都市",
            "play_cnt": "1025",
            "duration": "58分钟",
            "episode_cnt": 20,
            "publish_time": "2026-07-22 10:30:00",
            "cover": "https://example.com/cover.jpg",
            "intro": "作品简介"
        }
    ],
    "page": 1,
    "time": "2026-07-22 10:30:01"
}

详情响应

{
    "code": 200,
    "msg": "获取列表成功",
    "book_id": "7626291792958213182",
    "book_name": "示例短剧",
    "total": 20,
    "data": [
        {
            "video_id": "7625142218017229849",
            "title": "第1集",
            "firstPassTime": "2026-07-22 10:00:00"
        }
    ]
}

单集解析响应

{
    "code": 200,
    "msg": "解析成功",
    "video_id": "7625142218017229849",
    "url": "https://example.com/video.mp4",
    "data": {
        "url": "https://example.com/video.mp4"
    },
    "billing_type": "interface_vip",
    "points_used": 0,
    "time": "2026-07-22 10:30:02"
}

批量解析响应

{
    "code": 200,
    "msg": "批量解析完成 (成功: 2, 失败: 0)",
    "data": [
        {
            "code": 200,
            "msg": "解析成功",
            "video_id": "7618120805276191806",
            "url": "https://example.com/1.mp4"
        },
        {
            "code": 200,
            "msg": "解析成功",
            "video_id": "7618120703685971006",
            "url": "https://example.com/2.mp4"
        }
    ],
    "count": 2,
    "success_count": 2,
    "fail_count": 0,
    "billing_type": "interface_vip",
    "points_used": 0
}

统一通道响应

{
    "code": 200,
    "msg": "获取成功",
    "data": {
        "provider_original_fields": "上游原始结构会保留"
    },
    "channel": "pdd",
    "channel_no": 3,
    "channel_name": "拼多多",
    "channel_action": "search",
    "capabilities": [
        "search",
        "recommend",
        "latest",
        "filters",
        "rank",
        "detail",
        "play",
        "play_all",
        "play_batch"
    ],
    "normalized_data": [
        {
            "book_id": "BOOK_ID",
            "title": "示例作品",
            "cover_url": "https://example.com/cover.jpg",
            "episode_cnt": 80,
            "channel": "pdd",
            "source": "pdd"
        }
    ],
    "result_count": 1,
    "total": 1,
    "page": 1,
    "page_size": 20
}

完整代码示例

以下示例均检查业务 code,并设置合理超时。

cURL · Header 鉴权
curl --fail-with-body --location \
  --connect-timeout 8 --max-time 30 \
  -H "Accept: application/json" \
  -H "X-API-Key: api-YOUR_INTERFACE_KEY" \
  "https://orz.buaile.cn/api/api.php?channel=pdd&type=video_id&video_id=VIDEO_ID&level=1080p&fast=1"
Python · requests
import requests

url = "https://orz.buaile.cn/api/api.php"
params = {
    "channel": "pdd",
    "type": "video_id",
    "video_id": "VIDEO_ID",
    "level": "1080p",
    "fast": 1,
}
headers = {"X-API-Key": "api-YOUR_INTERFACE_KEY"}

response = requests.get(url, params=params, headers=headers, timeout=(8, 30))
response.raise_for_status()
payload = response.json()
if int(payload.get("code", 0)) != 200:
    raise RuntimeError(payload.get("msg", "接口调用失败"))

video_url = payload.get("url") or payload.get("data", {}).get("url")
print(video_url)
JavaScript · fetch
const url = new URL("https://orz.buaile.cn/api/api.php");
url.search = new URLSearchParams({
  channel: "pdd",
  type: "video_id",
  video_id: "VIDEO_ID",
  level: "1080p",
  fast: "1"
});

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 30000);
const response = await fetch(url, {
  headers: { "X-API-Key": "api-YOUR_INTERFACE_KEY" },
  signal: controller.signal
});
clearTimeout(timer);
const payload = await response.json();
if (Number(payload.code) !== 200) throw new Error(payload.msg || "接口调用失败");
console.log(payload.url ?? payload.data?.url);
PHP · cURL
<?php
$query = http_build_query([
    'channel' => 'pdd',
    'type' => 'video_id',
    'video_id' => 'VIDEO_ID',
    'level' => '1080p',
    'fast' => 1,
]);
$ch = curl_init('https://orz.buaile.cn/api/api.php?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 8,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: api-YOUR_INTERFACE_KEY',
    ],
]);
$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$payload = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ((int)($payload['code'] ?? 0) !== 200) {
    throw new RuntimeException($payload['msg'] ?? '接口调用失败');
}
echo $payload['url'] ?? $payload['data']['url'] ?? '';

错误码与处理建议

以 JSON 内的 code 为准,并记录 msg、channel、channel_action 便于排查。

code典型原因调用方处理
0未搜索到内容、单项解析失败或上游没有返回可用地址。检查 ID/页码;批量时逐项读取 data[].code。
200请求成功。继续读取 data 或 normalized_data。
400参数缺失、ID 格式错误、通道参数不符合要求。不要原样重试,先修正参数。
401缺少密钥、密钥不存在、使用了 api_key/key、或不是 api- 前缀。改用 apiKey/X-API-Key/Authorization,并检查密钥。
402按积分结算的接口密钥余额不足。充值或续费后再试。
403密钥禁用/过期,或接口密钥不可用当前通道。检查后台状态和全局通道开关。
404通道不存在或后台已关闭,常带 CHANNEL_DISABLED停止调用该通道并刷新可用通道配置。
409把红果错误地交给统一通道适配器。红果改用原生 type 路由。
422通道不支持该动作,或红果批量超过 50 个 ID。读取 capabilities,拆分批次。
500数据库或结算异常。稍后重试并保留请求参数和响应。
502上游通道异常或返回格式错误。指数退避重试,必要时切换通道。
503同一资源正在刷新、服务器繁忙、或麦萌服务端凭证未配置。等待 1~3 秒再试;不要高频循环。
524CDN 等待源站超时,并非标准业务 JSON。缩小请求、切换线路;服务端检查上游超时和缓存。
错误响应示例
{
  "code": 404,
  "msg": "当前内容通道未开启",
  "data": {
    "error_code": "CHANNEL_DISABLED",
    "channel": "xifan"
  },
  "time": "2026-07-22 10:30:00"
}

常见问题与排错

先按业务 code 定位,再检查通道、ID 来源和鉴权。

接口返回 401

确认密钥以 api- 开头,参数名必须是 apiKey,不要使用旧的 api_key

搜索有数据,解析失败

确认 video_id 来自同一 channel 的 detail;不要把不同通道 ID 混入一个批量请求。

河马详情报参数错误

必须把列表项里的 episode_cnt 与 book_id 一起传给 detail。

拼多多 ID 带冒号

这是合法的复合 ID(topic_id:feed_id),必须按字符串原样 URL 编码后传入。

喜番返回 m3u8

这是 HLS 播放清单,不是失败。使用支持 HLS 的播放器或 FFmpeg 合并为 MP4。

字段偶尔为空

上游未必提供作者、时长或上线时间。统一层只补已有字段,不伪造缺失值。

502 / 503 / 524

使用 1s、2s、4s 指数退避,最多 3 次;不要无限立即重试造成上游雪崩。

今日上新日期不对

服务端按 Asia/Shanghai 计算;检查 PHP 时区、服务器时间和 CDN/接口缓存是否已刷新。

HLS 转 MP4 示例

FFmpeg · 不重新编码快速封装
ffmpeg -i "https://example.com/index.m3u8" -c copy -movflags +faststart "output.mp4"
播放地址通常有时效,解析成功后应尽快使用;不要把一次解析得到的 URL 长期存入数据库当永久地址。

在线试用

公开接口可直接打开;解析接口请把示例密钥替换为自己的接口密钥。

已复制