浏览文档
指南
选择合适的媒体输出,控制下载范围,并将完成的任务转化为可使用的私有文件。
本页内容
从任务真正需要的内容开始
| 目标 | 选择 |
|---|---|
| 总结口述内容或建立文本索引 | 先读取已有字幕文本。仅在流程需要音频本身时下载音频,例如另行执行语音转文字。 |
| 处理语音或音频 | 仅音频输出,不携带应用无需使用的视频轨道。 |
| 展示短片段 | 设置 start_at 和 end_at,并确认两者位于原视频时长范围内。 |
| 播放或处理视频 | 选择带音频的 MP4,并设置适合应用的分辨率上限;本例使用 <=720。 |
保存所需的输出配置
选择一个标签,将完整请求保存为 download-request.json,并按来源修改 video_id。下方提交命令读取此文件,因此选择音频或片段会改变实际请求。
完整的带音频视频,分辨率上限为 720p。
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio_video",
"output_format": "mp4",
"video_quality": "<=720"
}
}用于收听或后续音频处理的文件。
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio",
"output_format": "mp3"
}
}从 00:00:05 到 00:00:10 的 MP4 片段。请使用适合所选视频的时间范围。
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio_video",
"output_format": "mp4",
"video_quality": "<=720",
"start_at": "00:00:05",
"end_at": "00:00:10"
}
}检查所有者访问及按字节计价
准备 Bash、jq,以及已保存的 CLI 配置档或 HTTP 使用的 FLASHDATA_API_KEY。密钥需要 youtube_download 权限。下载需要所有者访问,临时试用不包含此功能。CLI 示例使用 default 配置档;如使用命名配置,为每条命令添加 --profile NAME。
| 决策 | 做法 |
|---|---|
| 估算费用 | 使用返回的 creditsPerTb、bytesPerUnit 及预估输出字节数。下载不是按每次请求收取固定费用。 |
| 控制范围 | 提交前选择音频、片段或分辨率上限,并在应用中执行任务数量及消费规则。 |
| 记录实际费用 | 从完成的交付记录读取 usage。上传结算前可能预留 Credits;当前余额不是单任务消费上限。 |
flashdata account balance --json
flashdata account pricing --source youtube_download --json
flashdata account limits --json为每种输出使用私有目标
将真实目标参数私下保存为 storage.json,并放在版本控制之外。为每个视频及输出版本使用不同的 object_prefix;不同输出复用前缀会使应用记录更难核对。
| 凭据 | 用途 |
|---|---|
| FlashData 密钥 | 提交下载,并读取任务及交付 JSON。 |
| 存储上传凭据 | 将媒体写入预期 Bucket 及前缀。 |
| 应用存储身份 | 读取私有对象,或为已授权用户提供访问。 |
{
"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"
}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
)(
set -eu
umask 077
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
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" | curl --fail-with-body --silent --show-error --max-time 70 \
--request POST 'https://data.flashdata.dev/v1/queries' \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Content-Type: application/json' \
--data-binary @- --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"
)(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
STATUS_URL=$(jq -er '.links[] | select(.rel == "self") | .href' download-submission.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
"$STATUS_URL" --output job.json
jq '.job | {id, status, error}' job.json
)先读取交付记录,再访问媒体
状态为 completed 后,使用与提交一致的方式获取 delivery.json。签名结果 URL 返回 JSON;results[0].file_url 标识你的存储中的媒体。私有 file_url 需要存储读取身份,或由应用生成的访问链接。
(
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
)(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
jq -e '.job.status == "completed"' job.json >/dev/null
RESULTS_URL=$(jq -er '.links[] | select(.rel == "results") | .href' download-submission.json)
# Get the signed JSON URL without forwarding the API key to storage.
STORAGE_URL=$(curl --fail-with-body --silent --show-error --max-time 30 \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
--output /dev/null --write-out '%{redirect_url}' "$RESULTS_URL")
: "${STORAGE_URL:?No signed result URL was returned}"
curl --fail-with-body --silent --show-error --compressed --max-time 70 \
"$STORAGE_URL" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)检查实际交付内容
应获得一个文件位置、正的 file_size、MD5 及 usage。使用 file_size 记录交付对象大小;downloaded_bytes 是传输字段,不能替代 usage 中的最终费用。
(
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,验证大小和校验和,且不覆盖已有本地文件。
(
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 的生命周期。 |
flashdata runs show download-001 --json向智能体说明输出及交付标准
使用已保存的所有者访问和已配置的私有存储。
从 download-request.json 读取视频及输出,不擅自修改。
检查下载价格及可用 Credits,确保符合已批准的任务预算。
只提交一次,保存运行或任务 ID,然后读取该任务直到完成。
保存交付记录,处理前验证存储对象的大小及 MD5。
报告对象位置、所选格式、验证结果及实际用量。
提交结果不确定时检查已有工作,不创建替代访问或再次下载。
保护存储凭据,仅通过应用已配置的访问控制分享媒体。