BBDMGO文档
外部调用

猎流(LianLoader) 1.x

公共 API 接入

让第三方应用提交下载、查询结果,并正确处理重复请求。

公共 API 供第三方应用向正在运行的猎流直接添加下载任务,不弹出新建下载窗口。同一台电脑上使用疯狂URL联动或浏览器扩展时,不必开启它;接收另一台电脑上疯狂URL的投递时,需要开启它并创建“疯狂URL 远程投递”令牌。

启用服务

  1. 确认下载功能授权有效,进入“设置 → 远程投递与 API”(1.5.0 及更早版本叫“设置 → 公共 API”),打开“启用公共 API”。
  2. 本机调用保留监听地址 127.0.0.1。端口以页面显示为准,确认服务状态正常。
  3. 点击“创建 API 令牌”,“令牌类型”保持“第三方应用(公共 API)”,为调用应用填写名称和有效期,复制并妥善保存令牌。
  4. 调用应用在请求中附带 Authorization: Bearer <令牌>。

每个调用应用单独创建令牌,便于撤销。令牌只展示一次,重新生成会让旧令牌失效。令牌与产品授权独立,不能代替下载授权。

查看谁在用令牌

令牌列表里每一行的名称下面是令牌的开头部分(如 lldm_8be2aa2f••••),多个令牌时靠它对号入座。点击行上的人形图标打开“令牌使用记录”,可以看到:

  • 用过这个令牌的来源 IP 地址,每个地址的调用次数、首次和最近使用时间;
  • 对方请求里填写的应用名称(由调用方自己填,只作参考)。

只保留最近使用的 20 个地址。把令牌分给多台设备或其他人时,可以据此分辨是谁在用;出现不认识的地址,及时用行上的“重新生成令牌”图标换一个新令牌(旧令牌立即失效),或删除这个令牌。这项功能从桌面版 1.6.0 开始提供。

改监听配置会中断正在处理的 API 请求,已提交的下载不受影响。不要把带令牌的明文服务直接开放到不可信网络,也不要把令牌写进公开网页或截图。

NAS 版:接口与网页使用同一个地址和端口,不需要修改监听地址,但要先在网页的“设置 → 远程访问与 API”打开“启用 API 服务”(默认关闭)。令牌在同一页新建,类型分为“远程控制(手机 App、脚本)”“公共 API(第三方程序)”“疯狂URL 远程投递”。从外网调用时要走 HTTPS,见从外网访问。

接收另一台电脑上疯狂URL的投递

猎流 1.5.0 起支持此功能(疯狂URL需 5.3.0 及以上)。猎流装在家里电脑或服务器上、疯狂URL在另一台电脑上时,疯狂URL可以通过本服务远程投递,效果与同一台电脑上联用相同:保留完整请求信息、手动调用的下载要求和自动策略的投递去向,任务来源显示为疯狂URL。

  1. 打开“启用公共 API”,把“监听地址”改为 0.0.0.0,保存后确认服务状态正常。0.0.0.0 表示在所有 IPv4 网卡上接收连接,能访问到这台电脑的设备都能连到该端口。
  2. 点击“创建 API 令牌”,令牌类型选“疯狂URL 远程投递”,名称默认为“疯狂URL”,设置到期时间后创建并复制令牌。
创建 API 令牌窗口:令牌类型选为“疯狂URL 远程投递”,说明该令牌供另一台电脑上的疯狂URL投递下载或直播监控,应用名称为“疯狂URL”,到期时间 90 天(推荐)
选择“疯狂URL 远程投递”后,网页来源设置会隐藏。
  1. 在疯狂URL的“设置 → 下载 → 下载器连接”中选择“远程下载器”,填写这台电脑的地址、端口和令牌。完整步骤见发送到另一台电脑上的猎流。

令牌列表中,这类令牌的名称后面标有“远程投递”。两类令牌互相隔离:远程投递令牌只能用于疯狂URL投递,不能调用下文的公共接口,也不能配置网页来源;第三方应用令牌也不能冒充疯狂URL投递。类型在创建时确定,之后不能修改。远程投递使用疯狂URL传来的完整请求信息,不受“每次请求的参数优先级”影响;收到后按“直播监控”中的外部接收设置与下载重复处理处理。

两台电脑不在同一局域网、又没有公网 IP 时,可以借助组网工具连接,见没有公网 IP 时远程投递。

最小调用流程

将下面的 PORT、YOUR_TOKEN 和示例地址替换为自己的配置。本例只提交一个媒体或文件地址,不执行网页解析。

POST http://127.0.0.1:PORT/api/v1/downloads
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
Idempotency-Key: example-download-001

{
  "url": "https://media.example.com/video.mp4",
  "applicationName": "我的下载助手"
}
接口用途
GET /api/v1/info检查服务信息
POST /api/v1/downloads提交下载
GET /api/v1/downloads/{taskId}查询任务状态

响应中的业务结果位于 data。新建成功返回 201,从 data.taskId 或 data.statusUrl 查询进度。收到任务 ID 只表示已接受,不代表下载完成;调用应用只能查询自己创建的任务。

文件名、格式和请求信息

请求字段

POST /api/v1/downloads 的 JSON 请求体支持以下全部 5 个字段。字段名区分大小写,一次请求提交一个地址,不接受数组或批量地址。

字段JSON 类型必填说明与缺省行为
urlstring是完整下载地址,最多 8192 个字符。支持 http、https、rtmp、rtmps、rtsp;不接受在 URL 中嵌入用户名和密码。
applicationNamestring是调用程序的来源名称:2–30 个字符(按规范化并去除首尾空白后计),只能用文字和数字(任何语言均可),词之间可以用单个空格、连字符 - 或下划线 _;不能全是数字,不能含其他符号(如 $ ^ % * @)或表情。用于显示任务来源,不改变令牌权限或任务归属。
filenamestring 或 null否文件名,最多 200 个字符,不能包含目录。省略、null、空字符串或纯空白时,使用下载器命名规则。能否采用传入名称取决于下方的参数优先级。
formatstring 或 null否输出格式,允许值见下表。省略或 null 时使用默认配置;空字符串不是有效格式。
headersobject 或 null否目标网站的 HTTP 请求头,结构为“头名称:字符串值”。省略、null 或 {} 不覆盖默认请求头;不能传数组或整段请求头文本。

请求体不得超过 64 KiB。只使用上表字段;未知字段、重复 JSON 字段或类型错误会被拒绝。输出目录、代理、并发和重试等使用猎流设置,不通过本请求体指定。

filename 不能包含控制字符或 < > : " / \ | ? *,不能以点或空格结尾,也不能使用 CON、NUL、COM1 等保留设备名(包括带扩展名的形式)。实际扩展名会按下载规划修正,重名文件按规则避让,因此最终文件名可能与传入值不同。

applicationName 不符合上面的规则时返回 400 invalid_application_name。这套规则从桌面版 1.6.0、NAS 版 1.0.4 开始执行;更早的版本要求 3–100 个字符、不限制符号,按新规则取名在新旧版本上都能通过(至少 3 个字符即可)。它也不能使用以下保留名称:疯狂URL、CrazyURL、直播监控、监控中心、浏览器扩展、手动添加、未知、公共 API、LianLoader、猎流、连连下。比较时忽略大小写、空白及全角差异。它与令牌管理页填写的应用备注名称相互独立。

输出格式

以下是当前允许的 format 值,均为小写。接入时可用 GET /api/v1/info 的 data.formats 确认正在运行的版本支持哪些值。

值含义
auto自动选择输出格式;与省略字段后沿用默认配置不同。
flv请求 FLV 输出。
ts请求 TS 输出。
mp4请求 MP4 输出。
webm请求 WebM 输出;HLS 下载不支持此格式。
mkv请求 MKV 输出。
raw仅限 HTTP/HTTPS,按原始字节保存。例如 m3u8 地址会保存为清单文件,不下载其中的视频分片。

格式值合法不代表所有来源都能按该格式输出。普通 HTTP 文件下载不会因为传入 mp4 就完成转码;媒体内容与输出容器不兼容时也可能失败。下载后自动转换是独立步骤。

完整请求示例

下面展示全部 5 个字段,filename、format、headers 均可省略。示例地址和 Cookie 是占位值;不需要站点登录时,删除 Cookie 这一项。

POST http://127.0.0.1:PORT/api/v1/downloads
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
Idempotency-Key: example-download-002

{
  "url": "https://media.example.com/video.mp4",
  "applicationName": "我的下载助手",
  "filename": "示例视频.mp4",
  "format": "mp4",
  "headers": {
    "User-Agent": "MyDownloadHelper/1.0",
    "Referer": "https://media.example.com/",
    "Cookie": "session=YOUR_SITE_COOKIE"
  }
}

外层 HTTP 请求头用于调用猎流,与 JSON 中的 headers 分开:

外层请求头是否必需填写方式
Authorization是Bearer YOUR_TOKEN,使用猎流创建的 API 令牌。
Content-Type是application/json。
Idempotency-Key否,建议提供1–128 个可见 ASCII 字符,不能有空格,一次请求只传一个值。同一次逻辑提交重试时复用原键。

参数是否生效

传入可选字段前,检查参数优先级

“设置 → 远程投递与 API → 每次请求的参数优先级”中的文件名、输出格式、HTTP 头三项默认均关闭。要采用上例的传入值,需要勾选对应项;只对当前任务生效,不修改全局默认值。

设置状态处理方式
未勾选沿用默认配置,传入的非 null 字段会列在响应的 data.ignoredFields 中。
已勾选优先采用传入值;省略或 null 时回退默认配置。文件名为空白时也回退默认命名。

可从 GET /api/v1/info 的 data.preferFilename、data.preferFormat、data.preferHeaders 读取当前开关(boolean)。例如 data.ignoredFields 为 ["filename", "headers"],表示这两项未被采用。

创建成功后,查看 data.effectiveOptions.filename 和 data.effectiveOptions.format 确认规划的文件名与格式;它们不代表文件已下载成功或编码已经验证。即使某项将被忽略,传入值也必须先通过类型与格式校验。

JSON headers 的每个值都必须是字符串,不能是数字、布尔值、数组或 null。名称大小写不敏感,不能同时出现 Referer 和 referer;最多 32 项,名称和值的 UTF-8 字节数合计不超过 32 KiB。头名称须符合 HTTP 头命名规则,值不能含回车、换行、空字符等非法控制字符。

不允许传入:Host、Content-Length、Transfer-Encoding、Connection、Keep-Alive、Upgrade、TE、Trailer、Proxy-Authorization、Proxy-Connection。

启用“优先使用传入 HTTP 头”后:

  • 按名称覆盖默认头,未传入的默认头保留;{} 不会清除默认头。
  • Cookie 使用 name=value; name2=value2 形式的字符串,替换默认 Cookie 身份,不与另一个账号的 Cookie 合并。
  • "Cookie": "" 表示本次任务不使用默认 Cookie 或浏览器 Cookie 来源;与省略 Cookie 不同。

API 令牌与站点凭据分开填写

外层 Authorization 用于访问猎流,不会转发给下载网站。只有目标网站要求鉴权时,才在 JSON 的 headers.Authorization 中填写该网站的凭据,例如 "Authorization": "Bearer YOUR_SITE_TOKEN"。不要把猎流 API 令牌填在这里。

HTTP 头并非对所有下载方式都适用,非 HTTP 协议不会发送这些头或 Cookie。不支持的凭据组合会返回 400 credentials_not_supported;请检查目标网站要求、站点身份验证配置和下载引擎规则。

避免重复提交

超时重试时,保留原幂等键

同一次逻辑提交生成一次 Idempotency-Key。遇到网络超时,使用相同键、相同请求重试:有效期内会返回原回执,不再创建任务。键按调用应用隔离,保留 24 小时;相同键换了请求内容会返回冲突。

新的独立下载使用新键。多个应用即使使用相同键,也不能相互去重,仍需配合下载重复处理。

提示或结果如何处理
400 invalid_request检查字段名、JSON 类型、重复字段和不允许的请求头
400 invalid_application_name / invalid_url / invalid_filename / invalid_format / invalid_headers / invalid_idempotency_key按上方约束修正对应字段或幂等键
400 format_not_supported / credentials_not_supported请求格式或凭据不适用于当前下载方式,调整后再提交
413 / 415请求体超过 64 KiB,或未使用 application/json
200 且 data.replayed 为 true返回原提交回执,查询任务获取当前状态
409 duplicate_url全局策略跳过了重复下载,先查看已有任务
409 duplicate_requires_decision全局策略要求人工决定,API 不弹窗;在猎流处理或调整策略
409 idempotency_conflict同一个键对应了不同请求,检查调用逻辑
401 / 403核对令牌、有效期、应用权限和产品授权
429按响应的 Retry-After 等待,不要立即重复提交

删除任务后,有效期内的原提交回执仍可能返回,而查询任务会返回 404;不能把旧回执当作仍在运行的任务。

网页直接调用还需为该令牌配置准确的网页来源,浏览器自身的访问限制仍然有效。只需连接现成工具时,优先按该工具的接入说明填写服务地址和令牌。

Copyright © 2026 bdmgo. All rights reserved.

本页内容