接入指南 在线测试 登录免费注册

接入文档

三种接入方式按改造成本排序，任选其一。清洗只处理几 KB 的 m3u8 清单文本，正片分段始终直连源站 CDN，不经过本平台。

01播放地址加前缀（通用，推荐）

把站内所有资源站 m3u8 播放地址前拼接：

https://clean.ruseo.cn/p?key=【你的Key】&url=【原m3u8地址】

key 也可以放在 url 后面（参数顺序不限）；但苹果CMS 解析前缀只能往前拼地址，必须用上面 key 在前的写法。地址含 & 等参数时建议做 URL 编码；不含参数的资源站直链可以不编码直接拼接。

不带 key 也可以直接体验，但匿名请求每 IP 每日限 10 次；注册免费账号每日 50 次（同账号所有 Key 共享），专业版更高额度（专业版包月 ¥29 / 专业版包季 ¥79 / 专业版包年 ¥299）。

02苹果CMS V10 配置（改一处，全站生效）

  1. 后台 → 视频 → 播放器，找到资源站对应的 m3u8 播放器（如 m3u8 / json_m3u8），点编辑
  2. 解析前缀 填入：https://clean.ruseo.cn/p?key=【你的Key】&url=（key 放在 url 前面，CMS 拼接后自动生效；试运行阶段也可填 https://clean.ruseo.cn/p?url= 不带 Key）
  3. 保存后清一下 CMS 缓存，前台播放即走清洗

如果你的模板没有使用解析前缀字段，改播放页模板：找到输出播放地址的变量，套上代理前缀并编码：

原：{$maccms['vod_data'][0]['url']} 改：https://clean.ruseo.cn/p?url={$maccms['vod_data'][0]['url']|urlencode}
不同模板变量名不同，关键是找到输出 .m3u8 地址的那一行，套上前缀即可。

03H5 站引用 clean.js（自动接管）

在播放页 </body> 前加一行：

<script src="https://clean.ruseo.cn/clean.js"></script>

脚本会自动：改写页面上所有 .m3u8 链接与 video 地址；尽力改写苹果CMS模板的 player_aaaa.url 配置；暴露全局函数 ADCLEAN.proxy(url) 供你自己的播放器代码调用。

clean.js 依赖执行时机，部分模板先生效后加载会导致接管不到。最可靠仍是方式一/二。

04App 端接入

播放器取到播放地址后（或请求播放列表接口时），把 m3u8 地址替换为代理地址即可，播放器逻辑零改动：

GET https://clean.ruseo.cn/api/clean?key={你的Key}&url={原地址} 返回 JSON：{ report: 清洗报告, playlist: 净化后清单 }

或直接把代理地址交给播放器：

player.play("https://clean.ruseo.cn/p?key=" + KEY + "&url=" + URLEncoder.encode(url, "UTF-8"));

纯路径格式（部分 App/下载器会丢弃 ?key= 等查询参数，用这个格式更稳）：

GET https://clean.ruseo.cn/p/{Key}/{BASE64URL(原地址)}.m3u8 例：原地址 https://example.com/play/123/index.m3u8 编码后 https://clean.ruseo.cn/p/adc_xxx/aHR0cHM6Ly9leGFtcGxlLmNvbS9wbGF5LzEyMy9pbmRleC5tM3U4.m3u8

编码方法：对原地址做 URL-safe Base64（去掉末尾 =）。Java：Base64.getUrlEncoder().withoutPadding().encodeToString(url.getBytes())；JS：btoa(url).replace(/\+/g,'-').replace(/\//g,'_').replace(/=+$/,'')。也可以不带 .m3u8 后缀、省略 Key（计费模式下走匿名限流）。

App 请求没有 Referer，绑定域名的 Key 会自动放行；试运行阶段不带 key 也可用。

05API Key 的获取与使用

Key 用于标识接入方、统计用量和执行配额控制。获取只需三步：

  1. 注册账号（或 登录 已有账号）
  2. 进入 控制台 → 新建 Key，可填名称、绑定域名、日配额（0 = 不限）
  3. 把 Key 拼到清洗地址后面：&key=adc_xxxxxxxxxxxx
https://clean.ruseo.cn/p?key=adc_xxxxxxxxxxxx&url=【原m3u8地址】

参数顺序不限，key 也可以放在 url 后面（&key=adc_xxx）。苹果CMS 解析前缀只能往前拼地址，必须用上面 key 在前的写法。

原地址未编码直接拼时，即使自带 ?token= 等参数也能被完整识别；含参数的地址更推荐 URL 编码后拼接。

绑定域名：填了域名后，浏览器发起的请求会校验 Referer/Origin 必须匹配（App 端无 Referer 自动放行），防止 Key 被别人盗用。日配额：超过后当日返回 429，次日自动恢复。控制台可随时停用/启用/删除 Key，并查看每个 Key 的今日用量。

额度梯度：不带 key 的匿名请求每 IP 每日 10 次；免费注册的账号每日 50 次（同账号所有 Key 共享）；专业版 Key 日上限内不限量（专业版包月 ¥29 / 专业版包季 ¥79 / 专业版包年 ¥299，控制台在线支付自动开通，到期前续费时长自动叠加），达日上限自动回落按量余额扣费（余额不足返回 429，次日恢复）。带有效 Key 的请求不受匿名 IP 限流影响。单账号最多创建 10 个 Key。

按量付费（不想包月的选择）：给账户充值余额即可按量计费，清洗 1 次扣 ¥0.01 / 次（充值档位 ¥10 / ¥30 / ¥50）。计费顺序：专业版有效期（未达日上限）→ 每日免费 50 次 → 按量余额，即免费额度用完后才从余额扣费；专业版达日上限也自动转入按量扣费，余额扣完恢复免费额度限制。同一地址 24 小时内重复播放走缓存不计费；余额不足时返回 429 并提示充值。所有 Key 共享账户余额，控制台「余额充值」在线支付到账，清洗记录中扣费方式为「按量付费」。
状态码含义
401Key 缺失、无效或已被停用
403请求来源域名不在该 Key 的绑定域名列表
429超出日配额，次日自动恢复

06API 参考

端点说明
GET /p?url=清洗代理，直接返回净化后的 m3u8（主清单自动跟随）。参数：raw=1 返回原始清单；key= API Key
GET /p/{key}/{b64url}.m3u8纯路径格式（App 端推荐），b64url=URL-safe Base64(原地址) 去 padding；也可省略 {key} 走匿名限流
GET /api/clean?url=JSON：report（主清单+变体聚合清洗报告）+ playlist 净化后清单。参数：key= API Key
GET /api/stats?hours=24平台用量统计
POST /api/purge?url=|all=1清除缓存
GET /healthz健康检查

07常见问题