跳转到正文
中文
获取 API 密钥
浏览文档

API 参考文档

YouTube 下载 API

获取 API 密钥

将 YouTube 视频或音频下载到你的云存储。选择分辨率、格式和片段时长,然后跟踪异步任务直至完成。

YouTube 视频下载 API — Python 示例

构建请求

填写视频链接中的 11 位 ID,不要填写完整链接。

高级媒体选项

格式选择器会覆盖画质、帧率和音频语言选择。输出格式和剪辑边界仍然有效。剪辑结束时间必须晚于开始时间;任一边界均可省略。

存储目标

留空时使用 UTC 上传日期(YYYYMMDD)。

运行代码前,请在服务器上填写存储凭据,并确保其具有文件上传权限。

服务商凭证和存储要求
完成通知 WebhookWebhook 载荷、验证与重试

Markdown 用于已完成的结果。提交回执和任务状态保留原始字段。

POSThttps://data.flashdata.dev/v1/queries
import gzip
import json
import random
import time
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_download",
    "video_id": "jNQXAC9IVRw",
    "params": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "audio_language": "default",
        "upload_metadata": False,
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

def api_get(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response), response.headers

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, request, file_pointer, code, message, headers, new_url):
        return None

def read_result(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    try:
        with urllib.request.build_opener(NoRedirect).open(request, timeout=60):
            raise RuntimeError("Expected a result redirect")
    except urllib.error.HTTPError as response:
        if response.code != 302 or not response.headers.get("Location"):
            raise
        storage_url = response.headers["Location"]
        response.close()
    # Never forward the API key to storage.
    with urllib.request.urlopen(urllib.request.Request(storage_url, headers={"Accept-Encoding": "gzip"}), timeout=60) as response:
        content = response.read()
        if response.headers.get("Content-Encoding") == "gzip":
            content = gzip.decompress(content)
        return json.loads(content)

def link(job, relation):
    return next(item["href"] for item in job["links"] if item["rel"] == relation)

request = urllib.request.Request(
    "https://data.flashdata.dev/v1/queries",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={"Content-Type": "application/json", "X-API-Key": api_key},
    method="POST",
)
with urllib.request.urlopen(request, timeout=120) as response:
    submission = json.load(response)
jobs = submission.get("queries", [submission])
for submitted in jobs:
    print("Job:", submitted["id"])
    deadline = time.monotonic() + 300
    while time.monotonic() < deadline:
        status, headers = api_get(link(submitted, "self"))
        job = status.get("job", status)
        if job["status"] == "completed":
            result = job.get("result") if submitted["source"] == "youtube_download" and job.get("result") is not None else read_result(link(submitted, "results"))
            print(json.dumps(result, ensure_ascii=False, indent=2))
            break
        if job["status"] == "failed":
            raise RuntimeError(f"{submitted['id']}: {job.get('error', 'Job failed')}")
        hint = headers.get("Retry-After", "1")
        delay = max(1, min(5, int(hint))) if hint.isdigit() else 5
        time.sleep(min(delay * random.uniform(1, 1.2), max(0, deadline - time.monotonic())))
    else:
        raise TimeoutError(f"Still running; save this job ID: {submitted['id']}")
获取任务回执,然后轮询结果X-API-Key 身份验证

参数

发送 source 和 video_id 放在顶层。 数据源选项应放在 params. 可选字段可以省略。

请求体

sourcestring / 必填
设为 youtube_download。
video_idstring / 必填
11 字符的 YouTube 视频 ID,例如 FUfGcZ092b0。允许字母、数字、下划线和连字符。
恰好 11 个字符默认值: 未设置
接受的格式^[A-Za-z0-9_-]{11}$
paramsobject / 必填
此请求的设置。
callback_urlstring · nullable / 可选
仅支持异步和批量请求。完成通知 URL 必须是使用 443 端口的公开 HTTPS 地址,最多 2,048 个字符。不得包含用户凭证或 URL 片段。省略、设为 null 或空字符串时不发送通知。批量请求中,需在每个查询上设置此字段,不要放在 params 内部。
默认值: 未设置

视频与音频

params.download_typestring / 可选
audio_video 合并视频和音频;video 仅选择视频;audio 仅选择音频。
1 设为 11 个字符取值: audio_video / video / audio默认值: "audio_video"
params.video_qualitystring / 可选
视频分辨率选择。仅音频下载时请省略。
1 设为 40 个字符取值: best / worst / <=144 / ==144 / >=144 / <=360 / ==360 / >=360 / <=480 / ==480 / >=480 / <=720 / ==720 / >=720 / <=1080 / ==1080 / >=1080 / <=1440 / ==1440 / >=1440 / <=2160 / ==2160 / >=2160 / <=4320 / ==4320 / >=4320默认值: "<=720"
params.fpsstring / 可选
帧率约束:>=、<= 或 ==,后接 1 到 240 之间的值。仅下载音频时请省略。
1 设为 6 个字符默认值: 未设置
接受的格式^(?:>=|<=|==)(?:[1-9]\d?|1\d\d|2[0-3]\d|240)$
params.audio_languagestring / 可选
音频轨道选择。适用于 audio_video 和 audio。
1 设为 8 个字符取值: default / original默认值: "default"
params.audio_qualitystring / 可选
仅音频模式的比特率,单位为 kbps,或设为 best。数字选项必须以字符串发送。视频下载时省略。
1 设为 10 个字符取值: best / 320 / 256 / 192 / 128默认值: "best"
params.output_formatstring / 可选
视频:mp4、webm 或 mkv。音频:m4a、mp3 或 opus。
1 设为 10 个字符取值: mp4 / webm / mkv / m4a / mp3 / opus默认值: mp4 (video) / m4a (audio)
params.yt_dlp_formatstring / 可选
高级格式选择器,去除首尾空白后长度为 1 到 1,024 个字符。不接受控制字符。会覆盖 video_quality、fps 和 audio_language,随后忽略这些参数的值;输出格式和剪辑设置仍然有效。
1 设为 1,024 个字符默认值: 未设置
params.upload_metadataboolean / 可选
将元数据 JSON 文件与媒体文件一同上传到您的存储中。
true 或 false默认值: false

剪辑

params.start_atstring / 可选
剪辑开始时间,格式为 H:MM:SS 或 HH:MM:SS,范围为 00:00:00 到 12:00:00。仅提供 end_at 时,默认值为 00:00:00。
1 设为 8 个字符默认值: 未设置
接受的格式^\d{1,2}:[0-5]\d:[0-5]\d$
params.end_atstring / 可选
剪辑结束时间,格式为 H:MM:SS 或 HH:MM:SS,最长为 12:00:00。必须晚于 start_at。
1 设为 8 个字符默认值: 未设置
接受的格式^\d{1,2}:[0-5]\d:[0-5]\d$

存储目标

params.storageobject / 必填
已完成媒体文件的目标位置。仅接受列出的存储字段。
params.storage.storage_typestring / 必填
存储服务商:s3、s3_compatible、oss、gcs、azure、cos、bos 或 tos。
params.storage.storage_urlstring / 必填
存储桶或容器名称不能为空,最长 1,024 个字符。首尾空白会被去除。对于 s3,请使用有效的 AWS 存储桶名称,不要包含 URL 或文件夹路径;文件夹应填写在 object_prefix 中。
params.storage.object_prefixstring / 可选
对象键前缀,长度为 1 至 512 个字符。以斜杠分隔的每段允许使用 ASCII 字母、数字、点、下划线和连字符;不允许空段、. 和 ..。不能以斜杠开头。首尾空白及末尾的一个斜杠会被去除。YYYYMMDD 使用 UTC 上传日期,archive/YYYYMMDD 中的日期也遵循此规则。
默认值: "YYYYMMDD"
params.storage.access_keystring / 可选
用于 S3、S3-compatible、OSS、COS、BOS 或 TOS 的访问密钥;与 secret_key 配对使用。
params.storage.secret_keystring / 可选
用于 S3、S3 兼容存储、OSS、COS、BOS 或 TOS 的秘密密钥。
params.storage.endpoint_urlstring / 可选
S3 兼容存储或 OSS 的公网 HTTPS 端点。COS、BOS 和 TOS 根据 region 推导端点。
params.storage.regionstring / 可选
COS、BOS 和 TOS 必填;S3 和 S3 兼容存储的下载也应提供。COS 存储桶名称包含 APPID。
params.storage.service_accountobject / 可选
GCS 服务账户:project_id、client_email 和 PEM 格式的 private_key。
params.storage.account_namestring / 可选
Azure 存储账户名称。在 storage_url 中使用容器名称。
params.storage.sas_tokenstring / 可选
具有写入权限、包含到期时间和签名的 Azure 容器 SAS。

响应

请求构建器支持 Async 或 Batch 下载,必填 params.storage。HTTP 200 ,包含 status: pending 表示请求已接受,不表示已交付。批量请求会为每个视频 ID 返回一个任务回执。

提交 usage.credits 为 0。下载在成功交付后按交付的媒体数据量计费;可选元数据文件不会增加下载费用。

轮询 job.status ,直到 completed,然后获取结果 JSON。媒体详情见 results[0],包括已上传对象的 file_url、文件大小及校验值。

读取结果

任务完成后,将结果链接返回的 JSON 保存为 response.json。将以下代码保存为 read-response.py,再运行 python read-response.py。它读取文件信息,不会下载媒体或发起新请求。

read-response.py
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {name: result.get(name) for name in (
    "file_url", "file_size", "md5", "duration", "output_format"
)}
# Use your storage credentials to access the media at file_url.
print(json.dumps(output, ensure_ascii=False, indent=2))

状态信息可能在以下字段中包含媒体详情: job.result。默认 JSON 流程在有内联详情时直接使用,否则跟随 rel: results 链接;不要假定总有内联结果。

所有提交响应字段
字段描述
idstring下载任务 ID。
sourcestringyoutube_download.
statusstring任务被接受时为 pending。
created_atstringISO 8601 格式的任务创建时间。
usage.creditsnumber提交时为 0。下载在完成后按交付的数据量计费。
linksarray通过 self 链接查看任务状态,通过 results 链接获取已完成的输出。
links[].relstringself 或 results。
links[].hrefstring使用同一 API 密钥查询的 URL。
links[].methodstringGET.
已完成的媒体文件字段
字段描述
results[0].file_urlstring媒体文件在你的存储中的位置。
results[0].file_sizeinteger媒体文件大小,以字节为单位。
results[0].downloaded_bytesinteger用于计费的已交付媒体字节数。
results[0].md5string媒体文件的 MD5 校验和。
results[0].resolutionstring · nullable视频分辨率;仅音频输出或高度不可用时为 null。
results[0].durationnumber · nullable时长,以秒为单位(如有)。
results[0].output_formatstring输出文件格式。
results[0].fpsnumber · nullable帧率(如有)。
results[0].video_codecstring · nullable视频编解码器(如有)。
results[0].audio_codecstring · nullable音频编解码器(如有)。
results[0].dynamic_rangestring · nullable视频动态范围(如有)。
results[0].metadataobject · optional当 upload_metadata 为 true 时,提供元数据的 file_url、file_size 和 md5。元数据字节数不计入下载费用。

以上字段对应默认 JSON 响应。格式选项用于交付记录,不改变媒体文件。JSON、纯文本与 Markdown 格式。

异步与批量请求生命周期

提交后返回的是回执,而非结果。异步请求创建一个任务;批量请求会在以下字段中为各项返回独立任务: queries[] ,对应每个已接受的查询。请分别跟踪和获取每个任务。

提交到 data.flashdata.dev;从 api.flashdata.dev 读取任务状态与结果,两者使用同一 X-API-Key。以下 API 基础链接提供 Python 与 cURL 示例。

  1. 1. 保存任务 ID

    使用 Async 提交一个下载,或将多个下载请求放入 Batch 的 queries 数组。每项都需要 params.storage。保存每个返回的任务 ID。

    Async 请求与回执 · Batch 请求体

  2. 2. 检查状态

    GET https://api.flashdata.dev/v2/jobs/{jobId}

    pending / processing:轮询时加入延迟,并遵循 Retry-After (如有)。 completed:获取结果。 failed:检查 job.error.

    读取 job.status,而非提交回执的 status。

    检查状态 · Python 与 cURL

    任务状态 API 参考文档
  3. 3. 获取结果

    GET https://api.flashdata.dev/v2/jobs/{jobId}/results

    完成后先认证读取结果地址,再获取 302 存储 URL,不附带 API Key。在完成后的 24 小时内保存 JSON。

    此 JSON 描述已交付到你存储中的媒体。访问媒体文件.

    获取结果 · Python 与 cURL · 响应格式

    结果下载 API 参考文档

轮询和获取现有结果不会消耗查询积分。轮询超时不会取消任务:请保留任务 ID,避免重复提交会产生费用的任务。 错误代码与重试行为.

完成通知 Webhook

按查询订阅

设置 callback_url 放在异步请求的顶层,或 在每个查询内部 放在批量请求中,不要放在以下字段内部: params。无需单独发送 Webhook 注册请求。

使用端口为 443 的公开 HTTPS URL。每个任务达到以下状态时,FlashData 都会通过 POST 发送通知: completed 或 failed;事件包含的是链接,而不是结果本身。

确认接收并验证

返回 2xx ,确保先持久化接收事件。使用以下字段去重: delivery_id,也以以下形式发送: X-Delivery-Id。不会跟随重定向。

投递失败后使用指数退避重试,最多 总共 8 次尝试 ,且最多为 完成后 24 小时。请保留轮询作为备用方式。

回调不带签名。 通过以下接口确认任务 ID、数据源和终态: 需要身份验证的状态端点 ,再处理通知。交付 ID 用于去重,不能作为真实性证明。

Webhook 事件与字段示例
完成通知示例
{
  "delivery_id": "completion:job_example0001",
  "id": "job_example0001",
  "source": "youtube_download",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
      "method": "GET"
    }
  ]
}
字段描述
delivery_idstring稳定的投递标识符。使用此值对通知去重;X-Delivery-Id 请求头也会携带此值。
idstring任务 ID。
sourcestring请求的数据源。
statusstringcompleted 或 failed。
linksarray状态和结果链接。通知不包含结果内容或 API 密钥。
links[].relstringself 或 results。
links[].hrefstringManagement API 的绝对 URL;使用你的 API 密钥进行身份验证。
links[].methodstringGET.

完整 Webhook 协议与 URL 限制

文件批处理

每行上传一个视频 ID,创建 Bulk 任务时设置 source 为 youtube_download。共享选项应用于文件中的所有 ID。

必填存储目标放在 options.storage,媒体参数放在 options。单任务和 Batch 下载则使用 params.storage。

媒体文件会交付到你的云存储。已完成的文件批处理结果包含清单和结果分片,用于描述下载情况。 请在整个文件批处理任务完成后的 24 小时内保存清单和分片。

Bulk 处理 API · Python 与 cURL · Batch JSON 请求

为此来源构建 Bulk 工作流 · 暂停、恢复与错误处理

批量视频下载 — Python 工具包

存储目标

包含 params.storage 放在每个下载请求中。设置 storage_url 设为你的存储桶或容器名称,并提供具有写入权限的凭证。请将存储凭证保存在服务器上。

params.storage · S3 兼容存储目标
{
  "storage_type": "s3_compatible",
  "storage_url": "your-media-bucket",
  "object_prefix": "archive/YYYYMMDD",
  "endpoint_url": "https://your-s3-endpoint.example.com",
  "region": "your-provider-region",
  "access_key": "<storage-access-key>",
  "secret_key": "<storage-secret-key>"
}

object_prefix 默认为 YYYYMMDD,将替换为 UTC 上传日期。使用固定目录,或使用如下模板: archive/YYYYMMDD.

s3
提供具有写入权限的 access_key 和 secret_key。将 region 设为存储桶所在的 AWS 区域。
s3 示例
params.storage · s3
{
  "storage_type": "s3",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}
s3_compatible
提供 access_key、secret_key 和公网 HTTPS endpoint_url。按服务商要求设置 region;Cloudflare R2 使用 auto。
s3_compatible 示例
params.storage · s3_compatible
{
  "storage_type": "s3_compatible",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "endpoint_url": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
  "region": "auto"
}
azure
提供 account_name 和 sas_token;sas_token 为具有写入权限的容器 SAS(sp 包含 w),并包含资源 sr=c、到期时间 se、版本 sv 和签名 sig。storage_url 为容器名称。不要发送 endpoint_url、access_key 或 secret_key。
azure 示例
params.storage · azure
{
  "storage_type": "azure",
  "storage_url": "your-media-container",
  "account_name": "yourstorageaccount",
  "sas_token": "sv=2023-11-03&sr=c&sp=w&se=2099-01-01T00%3A00%3A00Z&sig=YOUR_SAS_SIGNATURE"
}
bos
提供 access_key、secret_key 和 region:bj、su 或 hkg。省略端点时,会根据 region 推导。请使用不含点的存储桶名称。
bos 示例
params.storage · bos
{
  "storage_type": "bos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "bj"
}
cos
提供 access_key、secret_key 和 ap-* 格式的 region,例如 ap-hongkong。storage_url 必须包含 APPID 后缀。不要发送 endpoint_url;它会根据 region 推导。
cos 示例
params.storage · cos
{
  "storage_type": "cos",
  "storage_url": "your-media-bucket-1234567890",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "ap-hongkong"
}
gcs
提供 service_account,其中包含 project_id、client_email(.gserviceaccount.com 地址)和服务账户的 PEM private_key。该账户必须具有存储桶写入权限。不要发送 access_key、secret_key、region 或 endpoint_url。
gcs 示例
params.storage · gcs
{
  "storage_type": "gcs",
  "storage_url": "your-media-bucket",
  "service_account": {
    "project_id": "your-project-id",
    "client_email": "[email protected]",
    "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n"
  }
}
oss
提供 access_key、secret_key,以及存储桶所在区域的公网 HTTPS endpoint_url。
oss 示例
params.storage · oss
{
  "storage_type": "oss",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "endpoint_url": "https://oss-cn-hongkong.aliyuncs.com"
}
tos
提供 access_key、secret_key 和带有 cn-、ap-、eu- 或 us- 前缀的 region。省略端点时,会根据 region 推导。请使用不含点的存储桶名称。
tos 示例
params.storage · tos
{
  "storage_type": "tos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "cn-beijing"
}

结果的 file_url 标识存储中的对象。私有对象需要存储服务商的授权或签名 URL;FlashData API 密钥不会授予你存储桶的访问权限。

如需完整的提交、轮询和下载流程,请参阅 将 YouTube 音频下载到 Amazon S3.

文件交付

任务的 rel: results 端点默认重定向到 结果 JSON,而不是 MP4 下载文件。FlashData 会将实际媒体上传到你提供的存储桶或容器。媒体保留期限遵循你的存储桶策略;任务的结果 JSON 在完成 24 小时后过期。

results[0].file_url 标识对象,但不会自动成为公开 URL 或签名 URL。使用你的存储 SDK 访问私有媒体,或在自己的服务器上生成短期有效的签名 URL。 请勿将 FlashData API 密钥发送给存储服务提供商。

启用 upload_metadata ,上传一个 {video_id}_meta.json 配套文件,位于相同前缀下。其位置和校验和见 results[0].metadata.

控制台的“浏览器下载”模式是独立功能。公共 API 下载使用您自己的存储;不要包含仅供控制台使用的 browser_delivery 设置。

错误恢复

对于上传失败或存储 403,请检查服务商、存储桶、区域、端点和对象写入权限。无法访问或私有的 file_url 本身并不表示上传失败:请通过你的存储服务商检查对象。

已删除或不可用的视频无法通过轮询恢复。对于不可用的格式,请检查 元数据格式、放宽画质限制或移除高级选择器。仅音频请求需要 m4a, mp3 或 opus;视频请求需要 mp4, webm 或 mkv.

如果结果 JSON 已过期,请先检查存储桶中已交付的媒体。重新提交会创建新的下载任务,可能再次产生费用;不会恢复原来的结果 JSON。

认证、余额、请求格式及限流错误的处理方法见 API 基础。提交超时可能已创建任务,重试前先检查已有任务。

错误与状态码 · 何时重试 · 速率限制

分步指南:下载一个视频并验证交付

价格

套餐用量费率每交付 1 GB订阅每个计费周期包含的积分
按量付费US$0.10无月费按需充值
MicroUS$0.08US$49.00 / 月包含 1,000 积分(相当于 US$50.00 的 API 用量)
StarterUS$0.07US$199.00 / 月包含 4,000 积分(相当于 US$200.00 的 API 用量)
ProUS$0.06US$499.00 / 月包含 10,000 积分(相当于 US$500.00 的 API 用量)
ScaleUS$0.05US$999.00 / 月包含 20,000 积分(相当于 US$1,000.00 的 API 用量)
BusinessUS$0.04US$1,999.00 / 月包含 40,000 积分(相当于 US$2,000.00 的 API 用量)

一个账户套餐,三种产品共用积分。由套餐内积分覆盖的用量不会重复收费。

当前价格与套餐限额