Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

Beispiele

Laden Sie ein Video auf Ihren Speicher herunter

Liefern Sie eine MP4 an Ihren Amazon S3-Bucket und rufen Sie dann die Datei mit Python oder Bash ab.

Auf dieser Seite

Bevor Sie anfangen

Verwenden Sie den Besitzerzugriff mit youtube_download-Berechtigung und verfügbaren Credits. Der Download ist nicht im temporären Agenten-Testzugang enthalten. Sie benötigen einen vorhandenen Amazon S3-Bucket und ein Video, das Sie herunterladen dürfen.

Wählen Sie Python 3.10+ mit Anfragen und boto3 oder Bash mit cURL, jq, OpenSSL und AWS CLI v2. Verwenden Sie unter Windows Git Bash für die Bash-Version.

NachweiseVerwendet für
FLASHDATA_API_KEYSenden Sie den Auftrag und holen Sie seinen Status und Lieferdatensatz ab.
FLASHDATA_STORAGE_ACCESS_KEY / FLASHDATA_STORAGE_SECRET_KEYEine S3-Upload-Identität, die an FlashData zum Schreiben an den von Ihnen gewählten Bucket und Präfix gesendet wird.
Ihr lokales AWS-Profil oder Ihre RolleLesen Sie das private Objekt mit boto3 oder AWS CLI in Schritt 4. Es benötigt s3:GetObject Zugriff.

1. Wählen Sie das Video und das Ziel

Erstellen Sie einen privaten Download-Video-Ordner außerhalb Ihres Repositorys. Speichern Sie dort request.json und öffnen Sie ein Terminal in diesem Ordner. Ersetzen Sie storage_url durch Ihren Bucket-Namen und Ihre Region durch die AWS-Region; Verwenden Sie ein 11-Zeichenvideo ID.

Dieses Rezept liefert Video mit Audio als MP4 mit bis zu 720p unter recipes/clip-001/. Halten Sie den Bucket privat. Verwenden Sie ein neues Präfix für einen separaten Download, damit ein anderer Job den Pfad dieses Objekts nicht überschreiben kann.

download-video/request.json
{
  "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. Einen Download-Job einreichen

Wählen Sie eine Version und speichern Sie das Skript neben request.json, bevor Sie es ausführen. Das Skript liest die drei Umgebungsvariablen oben oder fragt nach ihnen bei versteckten Eingabeaufforderungen. Agenten sollten sie aus ihrem geheimen Laden liefern. Legen Sie keine Schlüssel in request.json ein.

Ein neuer Job-001-Ordner sendet eine Async-Anfrage. Es speichert die Anforderung ohne Upload-Anmeldeinformationen, einen Zeitstempel, die HTTP-Antwort und den Job ID. Die Wiederverwendung dieses Ordners stoppt die Einreichung; es wird kein zweiter Job erstellt.

Installieren Sie in Ihrer Python-Umgebung
python -m pip install requests boto3
download-video/submit.py
# 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)
Laufen Sie von Download-Video /
python submit.py job-001

Voraussichtlicher Eingang

Erfolgsdrucke Eingereicht: job_... und speichert submission.json. Die Quittung bestätigt, dass die Arbeit angenommen wurde; es ist nicht die abgeschlossene Lieferung oder endgültige Gebühr.

job-001/submission.json · abgekürzt
{
  "id": "job_example",
  "source": "youtube_download",
  "status": "pending",
  "usage": {
    "credits": 0
  }
}

3. Warten Sie auf die Lieferung und speichern Sie seine Aufzeichnung

Speichern Sie collect.py neben submit.py oder collect.sh neben submit.sh. Führen Sie mit dem gleichen Job-001-Ordner aus. Es überprüft den gespeicherten Job einmal. Warten Sie bei der Bearbeitung oder Bearbeitung 10-Sekunden und führen Sie den gleichen Befehl erneut aus.

Wenn es fertig ist, speichert es delivery.json. Eine signierte Umleitung hier ruft den JSON-Lieferdatensatz, nicht die MP4; das Skript folgt ihm, ohne Ihren FlashData-Schlüssel weiterzuleiten. Eine gespeicherte delivery.json wird ohne eine weitere API-Anforderung wiederverwendet.

download-video/collect.py
# 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)
Überprüfen Sie den gespeicherten Job
python collect.py job-001

Was delivery.json enthält

Das Ergebnis beinhaltet file_url, file_size in Bytes und md5. Die Nutzung meldet die Gebühr des abgeschlossenen Auftrags. Behalten Sie den vollständigen Rekord. Die Datei URL benennt Ihr S3-Objekt; es macht keinen privaten Bucket öffentlich lesbar.

job-001/delivery.json · illustrierende Felder
{
  "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. Lesen Sie das private Objekt und überprüfen Sie es

Speichern Sie das Verifizierungsskript neben den anderen Skripten. Verwenden Sie Ihre konfigurierte lokale AWS-Identität mit Lesezugriff auf das Objekt. Das Skript überprüft, ob die Lieferung zum geplanten S3-Bucket, Präfix und Video-Dateinamen gehört, und lädt es dann in media.mp4.part herunter.

Nur eine übereinstimmende Bytezahl und MD5 erzeugen media.mp4 und verified.json. Die laufende Verifizierung überprüft erneut einen vorhandenen media.mp4 lokal. In diesem Schritt wird Ihr S3-Objekt gelesen; es wird kein weiterer FlashData-Download gesendet.

download-video/verify.py
# 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)
Überprüfen Sie die gespeicherte Lieferung
python verify.py job-001

Erfolgreiches Ergebnis

Die Bytezahl oben ist illustrativ. Sie haben jetzt die MP4 in Ihrem Bucket, eine verifizierte lokale Kopie und verified.json, die die Datei an ihren Job ID, Video ID, Objektschlüssel, Prüfsumme und gemeldete Nutzung bindet.

Terminal
Verified: .../job-001/media.mp4 — 1048576 bytes; MD5 matches.

Fortsetzung ohne einen zweiten Download

Was passierteNächste Maßnahme
Einreichung zeitversetzt oder kein Job ID wurde gespeichertBehalten Sie job-001 und überprüfen Sie History mit seinem Zeitstempel und Video. Löschen Sie den Ordner nicht, um eine andere Übermittlung zu erzwingen. Stellen Sie den ursprünglichen Job wieder her, bevor Sie entscheiden, ob eine neue Anfrage erforderlich ist.
Ausstehend/VerarbeitungWarten Sie 10 Sekunden und führen Sie dann das Sammeln mit Job-001 erneut aus. Es liest nur den bestehenden Job.
Job scheiterteÜberprüfen Sie job-status.json auf den Fehler. Beheben Sie die Video- oder Speicherkonfiguration, bevor Sie einen neuen Job explizit in einem neuen Ordner und Präfix starten.
401 / 403 / 402 / 429Überprüfen Sie den Schlüssel, die Berechtigung oder das Gleichgewicht. Für 429 lesen Sie Retry-After in den gespeicherten Headern und warten. Die Skripte versuchen die Einreichung nicht automatisch zu wiederholen.
Das Abrufen des Ergebnisses ist fehlgeschlagen oder das signierte URL ist abgelaufenRerun collect for job-001, um das vorhandene Ergebnis erneut anzufordern.
S3 AccessDeniedBeheben Sie die lokale AWS-Lese-Identität oder Bucket-Richtlinie. FlashData Upload-Zugriff und lokaler Lesezugriff sind getrennt.
Teildatei, falscher Pfad, Bytezahl oder MD5Bewahren Sie die gespeicherte Lieferung und Datei zur Inspektion auf. Für eine neue S3 gelesen, nachdem die Ursache zu beheben, bewegen media.mp4.part beiseite, dann erneut überprüfen. Nicht erneut einreichen.