Downloader 开发者 API

把 1,000+ 公开媒体平台的下载能力接入 Agent、后端服务、脚本或应用。

最近更新: 2026-08-02

概览

Downloader 提供一套异步 REST API，用于处理来自 1,000+ 平台/站点、且您有权下载的公开媒体。同一套 API 既能服务 AI Agent，也能接入后端服务、命令行脚本、自动化平台和您自己的产品。

基础路径：/api/v1
OpenAPI 3.1：/api/v1/openapi.json
能力发现：/api/v1/capabilities
鉴权方式：Bearer API Key
响应格式：JSON
输出格式：MP4 视频、M4A 音频或 192 kbps MP3 音频
平台覆盖：1,000+ 公开媒体平台/站点

原有 /api/agent 接口会继续兼容已安装的 Agent Skill；新接入应使用 /api/v1。

架构与任务生命周期

创建下载任务时，HTTP 连接不会一直等待媒体处理完成。SaaS API 负责验证调用方、预扣积分和创建任务；独立的下载处理 Worker 负责持久化编排、执行下载，并把结果写入私有临时存储。

submitting → accepted → queued → running → ready

错误终态包括 failed、canceled 和 expired，三种情况都会自动退回积分。成功产物通常保留一小时。

1. 创建 API Key

登录后打开 设置 → API 密钥 并创建 Key。完整的 sk_... 只显示一次，请保存在密钥管理服务或服务端环境变量中。

不要把 API Key 写入公开的浏览器 JavaScript、移动应用安装包、公共代码仓库、日志或分析事件。API 支持 CORS，但把永久 Key 暴露给终端用户并不安全；浏览器或移动端调用应先经过您自己的后端。

export DOWNLOADER_BASE_URL="https://your-downloader-domain.com"
export DOWNLOADER_API_KEY="sk_..."

2. 查询当前处理能力

该接口无需鉴权，可用于接入配置或运行时校验。

curl "$DOWNLOADER_BASE_URL/api/v1/capabilities"

响应会返回当前平台覆盖、profile、积分成本、输出格式、来源限制、文件寿命、签名链接寿命和请求上限。

1,000+ 平台覆盖

Downloader 覆盖 1,000+ 公开媒体平台/站点，包括视频、社交媒体、播客、新闻、教育和包含嵌入媒体的页面。一次接入即可处理这些来源类型，不必分别维护不同平台的下载器。

来源站发生变化时，具体链接的兼容性也可能变化。可靠的检查方式是提交公开链接并读取任务结果。

Profile	成本	视频最高分辨率	产物大小上限	处理超时
`economy`	1 积分	720p	750 MiB	15 分钟
`large`	5 积分	1080p	2 GiB	30 分钟

视频输出为 MP4，并且不进行视频转码；音频支持 M4A 或 192 kbps MP3。实际来源兼容性取决于当前解析器，以及公开来源是否提供可用格式。

产品功能边界

能力	当前是否支持
1,000+ 平台的公开单条视频链接	支持
嵌入媒体与通用公开网页	支持，前提是解析器能找到可用媒体
最高 720p 或 1080p 的 MP4 视频	支持，受 profile 与来源格式限制
M4A 或 192 kbps MP3 音频	支持
异步任务、轮询、取消、幂等与有限重试	支持
私有一小时文件、签名链接、HEAD、Range 与 SHA-256	支持
播放列表、直播、登录/Cookie 来源、私密媒体或 DRM	不支持
字幕、缩略图、任意底层下载参数或保证绕过访问限制	不支持

3. 查询积分余额

curl "$DOWNLOADER_BASE_URL/api/v1/credits" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY"

{
  "ok": true,
  "data": {
    "credits": 50,
    "creditPolicy": {
      "expires": false,
      "economyCost": 1,
      "largeCost": 5
    }
  }
}

4. 创建下载任务

每一个逻辑任务都应生成一个新的 Idempotency-Key，网络重试时保持这个 Key 不变。

curl -X POST "$DOWNLOADER_BASE_URL/api/v1/downloads" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8f52cbd3-video" \
  --data '{
    "sourceUrl": "https://media.example/video",
    "kind": "video",
    "profile": "economy",
    "videoMaxHeight": 720
  }'

音频示例：

{
  "sourceUrl": "https://media.example/video",
  "kind": "audio",
  "profile": "economy",
  "audioFormat": "mp3"
}

请求字段：

字段	必填	取值与行为
`sourceUrl`	是	公开 HTTP 或 HTTPS 地址，最长 4,096 字符
`kind`	否	默认 `video`，也可为 `audio`
`profile`	否	默认 `economy`，也可为 `large`
`videoMaxHeight`	仅视频	economy 为 144–720；large 为 144–1080
`audioFormat`	仅音频	默认 `m4a`，也可为 `mp3`

幂等保证

Key 只能包含安全 ASCII 字符，长度必须为 8–128。
使用相同 Key 和相同规范化请求重试时，会返回已有任务，不会再次扣积分。
相同 Key 搭配不同请求会返回 409 idempotency_conflict。
如果您确实要创建另一个下载，或主动重试已经失败的终态任务，请生成新 Key。
不带 Key 也能创建任务，但无法保证安全重试。

5. 轮询到任务完成

curl "$DOWNLOADER_BASE_URL/api/v1/downloads/JOB_ID" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY"

请使用指数退避，不要持续高频轮询。建议间隔为 2、4、8 秒，之后每 10 秒查询一次。

async function waitForDownload(baseUrl, apiKey, jobId) {
  const terminal = new Set(['ready', 'failed', 'canceled', 'expired']);
  let delay = 2000;

  while (true) {
    const response = await fetch(`${baseUrl}/api/v1/downloads/${jobId}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const body = await response.json();
    if (!response.ok) throw new Error(body.error?.message || 'API 请求失败');
    if (terminal.has(body.data.status)) return body.data;

    await new Promise((resolve) => setTimeout(resolve, delay));
    delay = Math.min(delay * 2, 10000);
  }
}

progress 包含处理阶段、百分比，以及来源可以提供时的已下载和总字节数。

6. 下载结果

当 status 为 ready 时，任务包含：

artifact：文件名、内容类型和大小
artifactExpiresAt：私有文件删除时间
downloadUrl：临时签名下载地址
downloadUrlExpiresAt：当前这条签名地址的失效时间

签名地址通常有效五分钟，支持 GET、HEAD 和单段 HTTP Range。如果地址已失效但文件仍在，请再次请求 GET /api/v1/downloads/{id} 获取新地址。

curl -L "$SIGNED_DOWNLOAD_URL" --output result.mp4

请及时下载，或把文件复制到您自己的持久存储。Downloader 的产物存储是有意设计成临时存储的。

列出和取消任务

最多列出最近 50 个任务：

curl "$DOWNLOADER_BASE_URL/api/v1/downloads?limit=20" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY"

取消运行中的任务：

curl -X DELETE "$DOWNLOADER_BASE_URL/api/v1/downloads/JOB_ID" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY"

取消操作是幂等的。如果任务已经进入终态，API 会直接返回当前任务。取消成功传递到处理服务后，预扣积分会自动退回。

错误与重试

错误使用固定结构：

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "Economy downloads support up to 720p"
  }
}

HTTP 状态	常见错误码	处理方式
401	`unauthorized`	更换或重新启用 API Key
402	`insufficient_credits`	购买积分后使用新 Key 提交
409	`idempotency_conflict`	恢复原请求体，或生成新 Key
413	`request_too_large`	JSON 请求体保持在 16 KiB 以下
422	`invalid_request`	修正字段或来源地址
429	`too_many_requests`	按 `Retry-After` 等待
503	`service_unavailable`	使用相同幂等 Key 退避重试

不要自动重试 401、402、409 或参数校验错误。网络失败、429 和 503 可以退避重试；当创建任务的响应结果不确定时，必须保留相同幂等 Key。

来源与安全边界

Downloader 只用于您有权下载的公开媒体。“1,000+ 平台”描述的是解析器覆盖范围，不代表下载授权，也不保证每条链接成功。服务不接收 Cookie 或登录会话，也不会绕过 DRM、地域限制、访问控制或来源限流。播放列表和直播会被拒绝。公开来源接口发生变化时，个别来源可能暂时不可用，请检查任务中的 error.code 与 error.message。

Agent 接入：只用 Skill，不用 MCP

Agent 通过可安装的 downloader-agent Skill 调用同一套 REST API，不需要 MCP Server。为 Skill 配置站点地址和 API Key：

export DOWNLOADER_API_URL="$DOWNLOADER_BASE_URL"
export DOWNLOADER_API_KEY="sk_..."

Skill 可以创建、轮询、查询积分、下载文件和取消任务；普通开发者直接使用本页 REST 示例即可。

版本策略

/api/v1 是稳定的公开契约。增加向后兼容字段不会改变版本；删除或修改现有字段时才会启用新的主版本路径。建议优先读取能力发现接口，避免在客户端写死限制。

生成 SDK 或接入 API 工具时，请导入 OpenAPI 3.1 文档。