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

指南

YouTube 下载最佳实践

选择合适的媒体输出,控制下载范围,并将完成的任务转化为可使用的私有文件。

本页内容

从任务真正需要的内容开始

目标选择
总结口述内容或建立文本索引先读取已有字幕文本。仅在流程需要音频本身时下载音频,例如另行执行语音转文字。
处理语音或音频仅音频输出,不携带应用无需使用的视频轨道。
展示短片段设置 start_at 和 end_at,并确认两者位于原视频时长范围内。
播放或处理视频选择带音频的 MP4,并设置适合应用的分辨率上限;本例使用 <=720。

保存所需的输出配置

选择一个标签,将完整请求保存为 download-request.json,并按来源修改 video_id。下方提交命令读取此文件,因此选择音频或片段会改变实际请求。

完整的带音频视频,分辨率上限为 720p。

download-request.json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "output_format": "mp4",
    "video_quality": "<=720"
  }
}

检查所有者访问及按字节计价

准备 Bash、jq,以及已保存的 CLI 配置档或 HTTP 使用的 FLASHDATA_API_KEY。密钥需要 youtube_download 权限。下载需要所有者访问,临时试用不包含此功能。CLI 示例使用 default 配置档;如使用命名配置,为每条命令添加 --profile NAME。

决策做法
估算费用使用返回的 creditsPerTb、bytesPerUnit 及预估输出字节数。下载不是按每次请求收取固定费用。
控制范围提交前选择音频、片段或分辨率上限,并在应用中执行任务数量及消费规则。
记录实际费用从完成的交付记录读取 usage。上传结算前可能预留 Credits;当前余额不是单任务消费上限。
免费检查 · CLI
flashdata account balance --json
flashdata account pricing --source youtube_download --json
flashdata account limits --json

为每种输出使用私有目标

将真实目标参数私下保存为 storage.json,并放在版本控制之外。为每个视频及输出版本使用不同的 object_prefix;不同输出复用前缀会使应用记录更难核对。

凭据用途
FlashData 密钥提交下载,并读取任务及交付 JSON。
存储上传凭据将媒体写入预期 Bucket 及前缀。
应用存储身份读取私有对象,或为已授权用户提供访问。
storage.json · S3
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1",
  "object_prefix": "media/video-001/mp4-720p-v1"
}
Linux / macOS · 私有文件
chmod 600 storage.json

只提交一次已保存请求

保存两个文件后运行其中一个标签。命令通过 stdin 加入 storage.json,并保存 download-submission.json。保留此回执。CLI 重试保留相同运行 ID;仅在明确创建新输出时使用新 ID。HTTP 提交不使用 CLI 的本地运行日志。

提交所选输出
(
set -eu
umask 077
test ! -e download-submission.json || { echo 'Inspect the saved submission first.' >&2; exit 1; }
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async \
  --run-id download-001 --output download-submission.json
)

先用 CLI 验证

预期返回 ok: true 和 data.dryRun: true。此步骤检查输入和 FlashData 访问,不提交任务;它不能证明上传凭据可以写入 Bucket。

免费预检查
(
set -eu
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async --dry-run --json
)

等待已有任务

提交回执不是媒体文件。CLI 等待任务,HTTP 命令读取一次状态。在截止时间内重复读取,直到 completed 或 failed。本地超时不会取消服务端任务。

等待已保存任务
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs wait "$JOB_ID"
)

先读取交付记录,再访问媒体

状态为 completed 后,使用与提交一致的方式获取 delivery.json。签名结果 URL 返回 JSON;results[0].file_url 标识你的存储中的媒体。私有 file_url 需要存储读取身份,或由应用生成的访问链接。

保存 delivery.json
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs result "$JOB_ID" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)

检查实际交付内容

应获得一个文件位置、正的 file_size、MD5 及 usage。使用 file_size 记录交付对象大小;downloaded_bytes 是传输字段,不能替代 usage 中的最终费用。

检查 delivery.json
(
set -eu
jq -e '.source == "youtube_download" and .status == "done"
  and (.results | length == 1) and (.results[0].file_size > 0)
  and (.results[0].md5 | test("^[a-fA-F0-9]{32}$"))' delivery.json >/dev/null
jq '{file: (.results[0] | {file_url, file_size, md5, duration, output_format}), usage}' delivery.json
)

验证来自 S3 的本地副本

将 OBJECT_KEY 设为 file_url 中的媒体对象 Key,包含前缀。使用具有读取权限的 AWS CLI、jq 和 OpenSSL。此步骤按所选请求保存 media.mp4 或 media.mp3,验证大小和校验和,且不覆盖已有本地文件。

S3 读取 · 不提交新 FlashData 查询
(
set -eu
# Requires AWS CLI configured for read access, jq and OpenSSL.
# Set OBJECT_KEY to the delivered media object's key from file_url.
: "${OBJECT_KEY:?Set the delivered S3 object key}"
BUCKET=$(jq -er '.storage_url' storage.json)
REGION=$(jq -er '.region' storage.json)
FORMAT=$(jq -er '.params.output_format' download-request.json)
case "$FORMAT" in mp4|mp3) ;; *) echo 'Choose a filename for this format.' >&2; exit 1 ;; esac
LOCAL_FILE="media.$FORMAT"
test ! -e "$LOCAL_FILE" || { echo 'Keep the existing local file.' >&2; exit 1; }
EXPECTED_BYTES=$(jq -er '.results[0].file_size' delivery.json)
EXPECTED_MD5=$(jq -er '.results[0].md5 | ascii_downcase' delivery.json)
aws s3 cp "s3://$BUCKET/$OBJECT_KEY" "$LOCAL_FILE" --region "$REGION" --only-show-errors
ACTUAL_BYTES=$(wc -c < "$LOCAL_FILE" | tr -d '[:space:]')
ACTUAL_MD5=$(openssl dgst -md5 "$LOCAL_FILE" | awk '{print $NF}')
test "$ACTUAL_BYTES" = "$EXPECTED_BYTES"
test "$ACTUAL_MD5" = "$EXPECTED_MD5"
echo 'Delivery verified'
)

从失败的阶段恢复

情况下一步
提交超时且无已确认任务 ID检查保存的 CLI 运行或请求历史。保留原输入,不要自动重新提交。
任务已接纳,但等待超时读取或恢复同一任务,不通过创建新下载继续等待。
上传失败读取任务错误,在有意重试前修复目标设置或写权限。
读取媒体返回 403检查存储读权限或应用生成的链接。FlashData API 密钥不能解锁 S3。
签名结果 JSON 过期在结果保留期内重新读取任务结果端点。已存媒体遵循 Bucket 的生命周期。
CLI · 检查已保存运行
flashdata runs show download-001 --json

向智能体说明输出及交付标准

智能体任务 · 提供视频、目标及预算
使用已保存的所有者访问和已配置的私有存储。
从 download-request.json 读取视频及输出,不擅自修改。
检查下载价格及可用 Credits,确保符合已批准的任务预算。
只提交一次,保存运行或任务 ID,然后读取该任务直到完成。
保存交付记录,处理前验证存储对象的大小及 MD5。
报告对象位置、所选格式、验证结果及实际用量。
提交结果不确定时检查已有工作,不创建替代访问或再次下载。
保护存储凭据,仅通过应用已配置的访问控制分享媒体。