Обзор документации
Примеры
Доставьте один MP4 в корзину Amazon S3, затем извлеките и проверьте файл с помощью Python или Bash.
На этой странице
Прежде чем начать
Используйте доступ владельца с разрешения youtube_download и доступные кредиты. Загрузка не включена в пробный доступ временного агента. Вам нужно существующее ведро Amazon S3 и видео, которое вы можете загрузить.
Выберите Python 3.10+ с запросами и boto3, или Bash с cURL, jq, OpenSSL и AWS CLI v2. В Windows используйте Git Bash для версии Bash.
| Полномочия | Используется для |
|---|---|
| FLASHDATA_API_KEY | Отправьте работу и получите ее статус и запись о доставке. |
| FLASHDATA_STORAGE_ACCESS_KEY / FLASHDATA_STORAGE_SECRET_KEY | Идентификатор загрузки S3, отправленный в FlashData для записи в выбранное вами ведро и префикс. |
| Ваш локальный профиль AWS или роль | Прочитайте частный объект с помощью boto3 или AWS CLI в шаге 4. Требуется s3:GetObject. |
1. Выберите видео и пункт назначения
Создайте приватную папку для загрузки видео вне вашего репозитория. Сохраните request.json там и откройте терминал в этой папке. Замените storage_url на имя ведра и регион на регион AWS; используйте видео 11-символ ID.
Этот рецепт обеспечивает видео с аудио как MP4, до 720p, под recipes/clip-001/.. Держите ведро в секрете. Используйте свежий префикс для отдельной загрузки, чтобы другая работа не могла переписать путь этого объекта.
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio_video",
"video_quality": "<=720",
"output_format": "mp4",
"storage": {
"storage_type": "s3",
"storage_url": "your-media-bucket",
"region": "us-east-1",
"object_prefix": "recipes/clip-001"
}
}
}2. Скачать One download job
Выберите одну версию и сохраните ее сценарий рядом с request.json перед запуском. Сценарий читает три переменные среды выше или запрашивает их при скрытых подсказках. Агенты должны снабжать их из своего секретного магазина. Не ставьте ключи в request.json.
Новая папка Job-001 отправляет один запрос на асинхронизацию. Он сохраняет запрос без загрузки учетных данных, метки времени, ответа HTTP и задания ID. Повторное использование этой папки останавливает отправку; это не создает вторую работу.
python -m pip install requests boto3# Save as download-video/submit.py.
import getpass
import json
import os
import re
import sys
from datetime import datetime, timezone
from pathlib import Path
import requests
ROOT = Path(__file__).resolve().parent
def read_json(path):
return json.loads(path.read_text(encoding="utf-8-sig"))
def secret(name):
value = os.environ.get(name) or getpass.getpass(name + ": ")
if not value.strip():
raise ValueError("Missing " + name)
return value
def main():
os.umask(0o077)
folder = sys.argv[1]
if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
raise ValueError("Use a simple output folder name, such as job-001.")
directory = ROOT / folder
if directory.exists():
raise ValueError("Keep this attempt. Run collect.py with the same folder.")
request = read_json(ROOT / "request.json")
storage = request["params"]["storage"]
if (request["source"] != "youtube_download"
or not re.fullmatch(r"[A-Za-z0-9_-]{11}", request["video_id"])
or request["params"]["download_type"] != "audio_video"
or request["params"]["output_format"] != "mp4"
or storage["storage_type"] != "s3"
or set(storage) != {"storage_type", "storage_url", "region", "object_prefix"}
or not re.fullmatch(r"[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]", storage["storage_url"])
or not re.fullmatch(r"[a-z0-9-]+", storage["region"])
or not re.fullmatch(r"[A-Za-z0-9_-]+(/[A-Za-z0-9_-]+)*", storage["object_prefix"])):
raise ValueError("Check the video, MP4 options and Amazon S3 destination.")
key = secret("FLASHDATA_API_KEY")
access = secret("FLASHDATA_STORAGE_ACCESS_KEY")
secret_key = secret("FLASHDATA_STORAGE_SECRET_KEY")
directory.mkdir(mode=0o700)
# Save the plan BEFORE sending. Keep upload credentials out of this file.
(directory / "request.json").write_text(json.dumps(request, indent=2), encoding="utf-8")
(directory / "submitted-at.txt").write_text(
datetime.now(timezone.utc).isoformat(), encoding="utf-8")
storage.update(access_key=access, secret_key=secret_key)
response = requests.post(
"https://data.flashdata.dev/v1/queries", json=request,
headers={"X-API-Key": key, "Accept": "application/json"},
timeout=(10, 120), allow_redirects=False)
(directory / "submission.json").write_bytes(response.content)
(directory / "submission-headers.txt").write_text(
"\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8")
(directory / "submission-http.txt").write_text(str(response.status_code))
if response.status_code not in (200, 201, 202):
raise ValueError(f"HTTP {response.status_code}. Inspect the saved attempt.")
receipt = response.json()
if (receipt.get("source") != "youtube_download"
or not re.fullmatch(r"[A-Za-z0-9_-]+", receipt.get("id", ""))):
raise ValueError("Missing job ID. Check History before submitting again.")
print("Submitted:", receipt["id"], "— keep", directory)
if __name__ == "__main__":
try:
main()
except (IndexError, KeyError, OSError, ValueError, requests.RequestException) as error:
print("Network request failed. Keep this attempt and inspect its saved files."
if isinstance(error, requests.RequestException) else str(error), file=sys.stderr)
sys.exit(1)python submit.py job-001curl --version
jq --version
openssl version
aws --version#!/usr/bin/env bash
# Save as download-video/submit.sh.
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
folder=${1:?Usage: bash submit.sh job-001}
[[ "$folder" =~ ^[A-Za-z0-9_-]+$ ]] || exit 2
[[ ! -e "$folder" ]] || { echo 'Keep this attempt. Run collect.sh with the same folder.' >&2; exit 1; }
jq -e '
.source == "youtube_download" and (.video_id | test("^[A-Za-z0-9_-]{11}$"))
and .params.download_type == "audio_video" and .params.output_format == "mp4"
and (.params.storage | .storage_type == "s3"
and (keys == ["object_prefix","region","storage_type","storage_url"])
and (.storage_url | test("^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$"))
and (.region | test("^[a-z0-9-]+$"))
and (.object_prefix | test("^[A-Za-z0-9_-]+(/[A-Za-z0-9_-]+)*$")))
' request.json >/dev/null
for name in FLASHDATA_API_KEY FLASHDATA_STORAGE_ACCESS_KEY FLASHDATA_STORAGE_SECRET_KEY; do
if [[ -z "${!name:-}" ]]; then
read -r -s -p "$name: " "$name"; printf '\n'
fi
[[ -n "${!name}" ]] || exit 1
export "$name"
done
mkdir -- "$folder"
# Save the plan before sending; upload credentials are added only to the pipe.
cp request.json "$folder/request.json"
date -u '+%Y-%m-%dT%H:%M:%SZ' > "$folder/submitted-at.txt"
jq '.params.storage += {
access_key: env.FLASHDATA_STORAGE_ACCESS_KEY,
secret_key: env.FLASHDATA_STORAGE_SECRET_KEY
}' "$folder/request.json" |
curl --silent --show-error --connect-timeout 10 --max-time 120 \
--request POST 'https://data.flashdata.dev/v1/queries' \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
--header 'Content-Type: application/json' --data-binary @- \
--dump-header "$folder/submission-headers.txt" \
--output "$folder/submission.json" --write-out '%{http_code}' > "$folder/submission-http.txt"
status=$(cat "$folder/submission-http.txt")
[[ "$status" =~ ^20[012]$ ]] || { echo "HTTP $status. Inspect the saved attempt." >&2; exit 1; }
jq -er 'if .source == "youtube_download" and (.id | test("^[A-Za-z0-9_-]+$"))
then "Submitted: " + .id else error("Missing job ID. Check History before resubmitting.") end' \
"$folder/submission.json"bash submit.sh job-001Ожидаемое получение
Успех печатает: job_... и сохраняет submission.json. Квитанция подтверждает, что работа была принята; это не завершенная доставка или окончательная плата.
{
"id": "job_example",
"source": "youtube_download",
"status": "pending",
"usage": {
"credits": 0
}
}3. Дождитесь доставки и сохраните свой рекорд
Сохраните collect.py рядом с submit.py или collect.sh рядом с submit.sh. Работайте с той же папкой Job-001. Один раз проверяйте сохраненную работу. Для ожидания или обработки подождите секунды 10 и снова запустите ту же команду.
После завершения он сохраняет delivery.json. Подписанное перенаправление здесь извлекает запись доставки JSON, а не MP4; сценарий следует за ней без пересылки ключа FlashData. Сохраненный delivery.json повторно используется без другого запроса API.
# Save as download-video/collect.py, beside submit.py.
import os
import re
import sys
from urllib.parse import urlsplit
import requests
from submit import ROOT, read_json, secret
def main():
os.umask(0o077)
folder = sys.argv[1]
if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
raise ValueError("Use the saved output folder name.")
directory = ROOT / folder
if (directory / "delivery.json").exists():
print("Already saved:", directory / "delivery.json")
return
receipt = read_json(directory / "submission.json")
job_id = receipt["id"]
if receipt["source"] != "youtube_download" or not re.fullmatch(r"[A-Za-z0-9_-]+", job_id):
raise ValueError("Inspect submission.json before continuing.")
headers = {"X-API-Key": secret("FLASHDATA_API_KEY"), "Accept": "application/json"}
url = "https://api.flashdata.dev/v2/jobs/" + job_id
def get(url, name, headers):
response = requests.get(url, headers=headers, timeout=(10, 120), allow_redirects=False)
(directory / name).write_bytes(response.content)
(directory / (name + ".headers")).write_text(
"\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8")
(directory / (name + ".http")).write_text(str(response.status_code))
return response
status = get(url, "job-status.json", headers)
if status.status_code != 200:
raise ValueError(f"HTTP {status.status_code}. Inspect job-status.json and its headers.")
job = status.json()["job"]
if job["id"] != job_id or job["source"] != "youtube_download":
raise ValueError("The job does not match the saved receipt.")
if job["status"] in ("pending", "processing"):
print(job["status"] + ". Wait 10 seconds, then run this command again.")
return
if job["status"] != "completed":
raise ValueError("Job " + job["status"] + ". Inspect job-status.json; do not resubmit.")
result = get(url + "/results", "delivery.pending.json", headers)
if result.status_code == 302:
location = result.headers.get("Location", "")
parsed = urlsplit(location)
if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:
raise ValueError("Expected an HTTPS result URL.")
# This URL retrieves the JSON delivery record, not the video.
# Never forward the FlashData key to the signed storage URL.
result = get(location, "delivery.pending.json", {})
if result.status_code != 200:
raise ValueError(f"HTTP {result.status_code}. Run collect.py again after resolving it.")
delivery = result.json()
if (delivery.get("source") != "youtube_download" or delivery.get("status") != "done"
or not isinstance(delivery.get("results"), list) or len(delivery["results"]) != 1):
raise ValueError("Inspect delivery.pending.json before using the result.")
(directory / "delivery.pending.json").replace(directory / "delivery.json")
print("Saved:", directory / "delivery.json")
print("Usage:", delivery.get("usage"))
if __name__ == "__main__":
try:
main()
except (IndexError, KeyError, OSError, ValueError, requests.RequestException) as error:
print("Network request failed. Keep this attempt and inspect its saved files."
if isinstance(error, requests.RequestException) else str(error), file=sys.stderr)
sys.exit(1)python collect.py job-001#!/usr/bin/env bash
# Save as download-video/collect.sh.
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
folder=${1:?Usage: bash collect.sh job-001}
[[ "$folder" =~ ^[A-Za-z0-9_-]+$ ]] || exit 2
if [[ -f "$folder/delivery.json" ]]; then
echo "Already saved: $folder/delivery.json"
exit 0
fi
id=$(jq -er 'select(.source == "youtube_download") | .id
| select(test("^[A-Za-z0-9_-]+$"))' "$folder/submission.json")
if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
read -r -s -p 'FLASHDATA_API_KEY: ' FLASHDATA_API_KEY; printf '\n'
fi
: "${FLASHDATA_API_KEY:?Set your key}"
url="https://api.flashdata.dev/v2/jobs/$id"
status=$(curl --silent --show-error --connect-timeout 10 --max-time 120 \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
--dump-header "$folder/job-status.json.headers" --output "$folder/job-status.json" \
--write-out '%{http_code}' "$url")
printf '%s' "$status" > "$folder/job-status.json.http"
[[ "$status" == 200 ]] || { echo "HTTP $status. Inspect job-status.json and its headers." >&2; exit 1; }
state=$(jq -er --arg id "$id" 'select(.job.id == $id and .job.source == "youtube_download")
| .job.status' "$folder/job-status.json")
case "$state" in
pending|processing) echo "$state. Wait 10 seconds, then run this command again."; exit 0 ;;
completed) ;;
*) echo "Job $state. Inspect job-status.json; do not resubmit." >&2; exit 1 ;;
esac
status=$(curl --silent --show-error --connect-timeout 10 --max-time 120 \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
--dump-header "$folder/result-headers.txt" --output "$folder/delivery.pending.json" \
--write-out '%{http_code}' "$url/results")
printf '%s' "$status" > "$folder/result-http.txt"
if [[ "$status" == 302 ]]; then
location=$(awk 'tolower($1)=="location:" {sub(/\r$/, "", $2); print $2}' "$folder/result-headers.txt")
[[ "$location" =~ ^https://[^/@[:space:]]+(/|$) ]] || { echo 'Expected an HTTPS result URL.' >&2; exit 1; }
# Retrieve the JSON delivery record without the FlashData key. Do not add -L.
status=$(curl --silent --show-error --compressed --proto '=https' \
--connect-timeout 10 --max-time 120 --dump-header "$folder/storage-result-headers.txt" \
--output "$folder/delivery.pending.json" --write-out '%{http_code}' "$location")
printf '%s' "$status" > "$folder/storage-result-http.txt"
fi
[[ "$status" == 200 ]] || { echo "HTTP $status. Resolve the error, then run collect.sh again." >&2; exit 1; }
jq -e '.source == "youtube_download" and .status == "done"
and (.results | type == "array" and length == 1)' "$folder/delivery.pending.json" >/dev/null
mv "$folder/delivery.pending.json" "$folder/delivery.json"
echo "Saved: $folder/delivery.json"
jq '{usage}' "$folder/delivery.json"bash collect.sh job-001Что такое delivery.json
Результат включает в себя file_url, file_size в байтах и md5. Сохраняйте полный рекорд. Файл URL именует ваш объект S3; он не делает частное ведро общедоступным.
{
"source": "youtube_download",
"status": "done",
"results": [
{
"file_url": "https://your-media-bucket.s3.us-east-1.amazonaws.com/recipes/clip-001/jNQXAC9IVRw.mp4",
"file_size": 1048576,
"md5": "0123456789abcdef0123456789abcdef"
}
]
}4. Прочитайте частный объект и проверьте его
Сохранить сценарий проверки рядом с другими сценариями. Используйте настроенную локальную идентификацию AWS с доступом к объекту чтения. Сценарий проверяет, что доставка принадлежит запланированному ведру S3, префиксу и имени видеофайла, после чего загружает его в media.mp4.part.
Только подходящее количество байтов и MD5 производят media.mp4 и verified.json. Запуск проверки снова проверяет существующий media.mp4 локально. Этот шаг считывает ваш объект S3; он не отправляет другую загрузку FlashData.
# Save as download-video/verify.py, beside submit.py.
import hashlib
import json
import os
import re
import sys
from contextlib import closing
from datetime import datetime, timezone
from urllib.parse import urlsplit
import boto3
from submit import ROOT, read_json
def main():
os.umask(0o077)
folder = sys.argv[1]
if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
raise ValueError("Use the saved output folder name.")
directory = ROOT / folder
request = read_json(directory / "request.json")
receipt = read_json(directory / "submission.json")
job = read_json(directory / "job-status.json")["job"]
delivery = read_json(directory / "delivery.json")
if (request["source"] != "youtube_download" or receipt["source"] != "youtube_download"
or job["id"] != receipt["id"] or job["source"] != "youtube_download"
or job["status"] != "completed" or delivery.get("source") != "youtube_download"
or delivery.get("status") != "done" or len(delivery["results"]) != 1):
raise ValueError("Check the saved request, receipt, status and delivery.")
storage = request["params"]["storage"]
bucket, region, prefix = (storage[k] for k in ("storage_url", "region", "object_prefix"))
file = delivery["results"][0]
parsed = urlsplit(file["file_url"])
# This recipe uses an ASCII prefix and the MP4 filename generated for the video.
object_key = prefix + "/" + request["video_id"] + ".mp4"
if (storage["storage_type"] != "s3" or parsed.scheme != "https"
or parsed.netloc != bucket + ".s3." + region + ".amazonaws.com"
or parsed.path != "/" + object_key or parsed.query or parsed.fragment
or type(file.get("file_size")) is not int or file["file_size"] <= 0
or not re.fullmatch(r"[A-Fa-f0-9]{32}", file.get("md5", ""))):
raise ValueError("Delivery URL, byte count or MD5 does not match this recipe's request.")
local = directory / "media.mp4"
pending = directory / "media.mp4.part"
if not local.exists():
# Boto3 uses your local AWS read identity, not the upload key sent to FlashData.
with pending.open("xb") as output:
s3 = boto3.client("s3", region_name=region)
with closing(s3.get_object(Bucket=bucket, Key=object_key)["Body"]) as stream:
while chunk := stream.read(1024 * 1024):
output.write(chunk)
local = pending
size, digest = 0, hashlib.md5(usedforsecurity=False)
with local.open("rb") as stream:
while chunk := stream.read(1024 * 1024):
size += len(chunk)
digest.update(chunk)
if size != file["file_size"] or digest.hexdigest() != file["md5"].lower():
raise ValueError("Size or MD5 mismatch. Keep the local file for inspection.")
final = directory / "media.mp4"
if local == pending:
pending.rename(final)
record = {
"job_id": receipt["id"], "video_id": request["video_id"],
"bucket": bucket, "object_key": object_key, "bytes": size, "md5": digest.hexdigest(),
"verified_at": datetime.now(timezone.utc).isoformat(), "usage": delivery.get("usage"),
}
(directory / "verified.json").write_text(json.dumps(record, indent=2), encoding="utf-8")
print("Verified:", final, "—", size, "bytes; MD5 matches.")
if __name__ == "__main__":
try:
main()
except Exception as error:
print(str(error), file=sys.stderr)
sys.exit(1)python verify.py job-001#!/usr/bin/env bash
# Save as download-video/verify.sh.
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
folder=${1:?Usage: bash verify.sh job-001}
[[ "$folder" =~ ^[A-Za-z0-9_-]+$ ]] || exit 2
jq -e --slurpfile r "$folder/request.json" --slurpfile s "$folder/submission.json" \
--slurpfile j "$folder/job-status.json" '
$r[0] as $r | $s[0] as $s | $j[0].job as $j
| $r.params.storage as $store
| ($store.object_prefix + "/" + $r.video_id + ".mp4") as $key
| .results[0] as $f
| $r.source == "youtube_download" and $s.source == "youtube_download"
and $j.id == $s.id and $j.source == "youtube_download" and $j.status == "completed"
and .source == "youtube_download" and .status == "done"
and (.results | type == "array" and length == 1)
and $store.storage_type == "s3"
and $f.file_url == ("https://" + $store.storage_url + ".s3." + $store.region + ".amazonaws.com/" + $key)
and ($f.file_size | type == "number" and . > 0 and . == floor)
and ($f.md5 | test("^[A-Fa-f0-9]{32}$"))
' "$folder/delivery.json" >/dev/null
bucket=$(jq -er '.params.storage.storage_url' "$folder/request.json")
region=$(jq -er '.params.storage.region' "$folder/request.json")
key=$(jq -er '.params.storage.object_prefix + "/" + .video_id + ".mp4"' "$folder/request.json")
local_file="$folder/media.mp4"
if [[ ! -e "$local_file" ]]; then
local_file="$folder/media.mp4.part"
[[ ! -e "$local_file" ]] || { echo 'Keep the partial file; inspect it before retrying.' >&2; exit 1; }
# AWS CLI uses your configured read identity; no FlashData key is sent to S3.
aws s3 cp "s3://$bucket/$key" "$local_file" --region "$region" --only-show-errors
fi
bytes=$(wc -c < "$local_file" | tr -d '[:space:]')
md5=$(openssl dgst -md5 "$local_file" | awk '{print tolower($NF)}')
expected_bytes=$(jq -er '.results[0].file_size' "$folder/delivery.json")
expected_md5=$(jq -er '.results[0].md5 | ascii_downcase' "$folder/delivery.json")
[[ "$bytes" == "$expected_bytes" && "$md5" == "$expected_md5" ]] ||
{ echo 'Size or MD5 mismatch. Keep the local file for inspection.' >&2; exit 1; }
if [[ "$local_file" != "$folder/media.mp4" ]]; then
mv "$local_file" "$folder/media.mp4"
fi
jq --slurpfile r "$folder/request.json" --slurpfile s "$folder/submission.json" \
--arg key "$key" --arg md5 "$md5" --argjson bytes "$bytes" '
{job_id: $s[0].id, video_id: $r[0].video_id, bucket: $r[0].params.storage.storage_url,
object_key: $key, bytes: $bytes, md5: $md5, verified_at: (now | todateiso8601), usage}
' "$folder/delivery.json" > "$folder/verified.json"
echo "Verified: $folder/media.mp4 — $bytes bytes; MD5 matches."bash verify.sh job-001Успешный результат
Количество байтов выше является иллюстративным. Теперь у вас есть MP4 в ведре, проверенная локальная копия и verified.json, связывающий файл с его работой ID, видео ID, ключ объекта, контрольная сумма и отчет об использовании.
Verified: .../job-001/media.mp4 — 1048576 bytes; MD5 matches.Резюме без второй загрузки
| Что случилось? | Следующее действие |
|---|---|
| Отсроченная подача или отсутствие работы ID были сохранены | Держите вакансию-001 и проверяйте History с помощью метки времени и видео. Не удаляйте папку, чтобы заставить другую заявку. Восстановите оригинальную работу, прежде чем решить, нужен ли новый запрос. |
| Отсрочка/обработка | Подождите секунды 10, затем повторите сбор с помощью работы-001. Он читает только текущую работу. |
| Работа провалилась | Проверьте job-status.json на наличие ошибки. Исправьте конфигурацию видео или хранилища, прежде чем явно начинать новую работу в новой папке и префиксе. |
| 401 / 403 / 402 / 429 | Проверьте ключ, разрешение или баланс. Для 429 прочитайте Retry-After в сохраненных заголовках и подождите. Сценарии не автоматически повторяют представление. |
| Получение результата не удалось или его подписанный URL истек. | Повторно собрать для работы-001, чтобы запросить существующий результат снова. |
| S3 AccessDenied | Исправьте локальную политику AWS считывания идентичности или ведра. Доступ к загрузке FlashData и доступ к локальному чтению являются отдельными. |
| Частичный файл, неправильный путь, количество байтов или MD5 | Сохраните сохраненную доставку и файл для проверки. Для свежего чтения S3 после устранения причины отведите media.mp4.part в сторону, а затем повторите проверку. Не возвращайся. |