公共 API 接入

公共 API 供第三方应用向正在运行的猎流直接添加下载任务，不弹出新建下载窗口。正常使用疯狂URL联动或浏览器扩展时，不必开启它。

启用服务复制本节链接

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

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

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

最小调用流程复制本节链接

将下面的 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": "我的下载助手"
}

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

文件名、格式和请求信息复制本节链接

请求字段复制本节链接

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

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

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

applicationName 不能包含控制字符或隐藏格式字符，也不能使用以下保留名称：疯狂URL、CrazyURL、直播监控、监控中心、浏览器扩展、手动添加、未知、公共 API、LianLoader、猎流、连连下。比较时忽略大小写、空白及全角差异。它与令牌管理页填写的应用备注名称相互独立。

输出格式复制本节链接

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

格式值合法不代表所有来源都能按该格式输出。普通 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 分开：

参数是否生效复制本节链接

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

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

HTTP 头与 Cookie复制本节链接

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 不同。

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

避免重复提交复制本节链接

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

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

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