浏览文档
API 参考文档
YouTube 下载 API
将 YouTube 视频或音频下载到你的云存储。选择分辨率、格式和片段时长,然后跟踪异步任务直至完成。
构建请求
填写视频链接中的 11 位 ID,不要填写完整链接。
高级媒体选项
格式选择器会覆盖画质、帧率和音频语言选择。输出格式和剪辑边界仍然有效。剪辑结束时间必须晚于开始时间;任一边界均可省略。
存储目标
留空时使用 UTC 上传日期(YYYYMMDD)。
运行代码前,请在服务器上填写存储凭据,并确保其具有文件上传权限。
服务商凭证和存储要求完成通知 Webhook
Webhook 载荷、验证与重试Markdown 用于已完成的结果。提交回执和任务状态保留原始字段。
https://data.flashdata.dev/v1/queries参数
发送 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。它读取文件信息,不会下载媒体或发起新请求。
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。 |
sourcestring | youtube_download. |
statusstring | 任务被接受时为 pending。 |
created_atstring | ISO 8601 格式的任务创建时间。 |
usage.creditsnumber | 提交时为 0。下载在完成后按交付的数据量计费。 |
linksarray | 通过 self 链接查看任务状态,通过 results 链接获取已完成的输出。 |
links[].relstring | self 或 results。 |
links[].hrefstring | 使用同一 API 密钥查询的 URL。 |
links[].methodstring | GET. |
已完成的媒体文件字段
| 字段 | 描述 |
|---|---|
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. 保存任务 ID
使用 Async 提交一个下载,或将多个下载请求放入 Batch 的 queries 数组。每项都需要 params.storage。保存每个返回的任务 ID。
2. 检查状态
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing:轮询时加入延迟,并遵循Retry-After(如有)。completed:获取结果。failed:检查job.error.读取 job.status,而非提交回执的 status。
任务状态 API 参考文档3. 获取结果
GET https://api.flashdata.dev/v2/jobs/{jobId}/results完成后先认证读取结果地址,再获取 302 存储 URL,不附带 API Key。在完成后的 24 小时内保存 JSON。
此 JSON 描述已交付到你存储中的媒体。访问媒体文件.
结果下载 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 | 请求的数据源。 |
statusstring | completed 或 failed。 |
linksarray | 状态和结果链接。通知不包含结果内容或 API 密钥。 |
links[].relstring | self 或 results。 |
links[].hrefstring | Management API 的绝对 URL;使用你的 API 密钥进行身份验证。 |
links[].methodstring | GET. |
文件批处理
每行上传一个视频 ID,创建 Bulk 任务时设置 source 为 youtube_download。共享选项应用于文件中的所有 ID。
必填存储目标放在 options.storage,媒体参数放在 options。单任务和 Batch 下载则使用 params.storage。
媒体文件会交付到你的云存储。已完成的文件批处理结果包含清单和结果分片,用于描述下载情况。 请在整个文件批处理任务完成后的 24 小时内保存清单和分片。
存储目标
包含 params.storage 放在每个下载请求中。设置 storage_url 设为你的存储桶或容器名称,并提供具有写入权限的凭证。请将存储凭证保存在服务器上。
{
"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 示例
{ "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 示例
{ "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 示例
{ "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 示例
{ "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 示例
{ "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 示例
{ "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 示例
{ "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 示例
{ "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 | 无月费 | 按需充值 |
| Micro | US$0.08 | US$49.00 / 月 | 包含 1,000 积分(相当于 US$50.00 的 API 用量) |
| Starter | US$0.07 | US$199.00 / 月 | 包含 4,000 积分(相当于 US$200.00 的 API 用量) |
| Pro | US$0.06 | US$499.00 / 月 | 包含 10,000 积分(相当于 US$500.00 的 API 用量) |
| Scale | US$0.05 | US$999.00 / 月 | 包含 20,000 积分(相当于 US$1,000.00 的 API 用量) |
| Business | US$0.04 | US$1,999.00 / 月 | 包含 40,000 积分(相当于 US$2,000.00 的 API 用量) |
一个账户套餐,三种产品共用积分。由套餐内积分覆盖的用量不会重复收费。
当前价格与套餐限额