Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Exemples

Télécharger une vidéo dans votre stockage

Livrez un MP4 dans votre bucket Amazon S3, puis récupérez et vérifiez le fichier avec Python ou Bash.

Sur cette page

Avant de commencer

Utilisez un accès rattaché à un compte propriétaire, avec l’autorisation youtube_download et des crédits disponibles. Le téléchargement n’est pas inclus dans l’accès d’essai des agents temporaires. Vous devez disposer d’un bucket Amazon S3 et être autorisé à télécharger la vidéo choisie.

Choisissez Python 3.10+ avec requests et boto3, ou Bash avec cURL, jq, OpenSSL et AWS CLI v2. Sous Windows, utilisez Git Bash pour la version Bash.

Identifiant d’accèsUtilisation
FLASHDATA_API_KEYSoumettre la tâche, consulter son état et récupérer son relevé de livraison.
FLASHDATA_STORAGE_ACCESS_KEY / FLASHDATA_STORAGE_SECRET_KEYIdentité d’envoi S3 transmise à FlashData pour écrire dans le bucket et le préfixe choisis.
Votre profil ou rôle AWS localLire l’objet privé avec boto3 ou AWS CLI à l’étape 4. L’autorisation s3:GetObject est nécessaire.

1. Choisir la vidéo et la destination

Créez un dossier privé download-video en dehors de votre dépôt. Enregistrez-y request.json et ouvrez un terminal dans ce dossier. Remplacez storage_url par le nom de votre bucket et region par sa région AWS ; utilisez un identifiant vidéo à 11 caractères.

Cet exemple livre la vidéo avec son audio au format MP4, jusqu’à 720p, sous recipes/clip-001/. Gardez le bucket privé. Choisissez un nouveau préfixe pour un téléchargement distinct afin qu’une autre tâche n’écrase pas cet objet.

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. Soumettre une tâche de téléchargement

Choisissez une version et enregistrez son script à côté de request.json avant de l’exécuter. Le script lit les trois variables d’environnement ci-dessus ou vous les demande sans les afficher. Les agents doivent les fournir depuis leur gestionnaire de secrets. Ne placez pas de clés dans request.json.

Un nouveau dossier job-001 déclenche une requête asynchrone. Il conserve la requête sans les identifiants d’envoi, un horodatage, la réponse HTTP et l’identifiant de tâche. Réutiliser ce dossier bloque la soumission ; cela ne crée pas une deuxième tâche.

Installer dans votre environnement Python
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)
Exécuter depuis download-video/
python submit.py job-001

Reçu attendu

En cas de succès, le script affiche Submitted: job_… et enregistre submission.json. Ce reçu confirme l’acceptation de la tâche ; il ne confirme ni sa livraison ni son coût final.

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

3. Attendre la livraison et enregistrer son relevé

Enregistrez collect.py à côté de submit.py, ou collect.sh à côté de submit.sh. Exécutez-le avec le même dossier job-001. Il vérifie une fois l’état de la tâche enregistrée. Pour pending ou processing, attendez 10 secondes, puis relancez la même commande.

Lorsque l’état est completed, le script enregistre delivery.json. La redirection signée récupère ici le relevé de livraison JSON, pas le MP4 ; le script la suit sans transmettre votre clé FlashData. Un fichier delivery.json déjà enregistré est réutilisé sans nouvel appel API.

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)
Vérifier la tâche enregistrée
python collect.py job-001

Contenu de delivery.json

Le résultat contient file_url, file_size en octets et md5. usage indique le coût de la tâche terminée. Conservez le relevé complet. L’URL du fichier désigne votre objet S3 ; elle ne rend pas un bucket privé accessible publiquement.

job-001/delivery.json · exemple de champs
{
  "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. Lire l’objet privé et le vérifier

Enregistrez le script de vérification à côté des autres scripts. Utilisez votre identité AWS locale configurée avec un droit de lecture sur l’objet. Le script vérifie que la livraison correspond au bucket S3, au préfixe et au nom de fichier vidéo prévus, puis télécharge le fichier dans media.mp4.part.

media.mp4 et verified.json ne sont créés que si la taille en octets et le MD5 correspondent. Une nouvelle vérification contrôle localement un media.mp4 existant. Cette étape lit votre objet S3 ; elle ne soumet pas un autre téléchargement FlashData.

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)
Vérifier la livraison enregistrée
python verify.py job-001

Résultat réussi

La taille en octets ci-dessus est illustrative. Vous disposez maintenant du MP4 dans votre bucket, d’une copie locale vérifiée et de verified.json, qui relie le fichier à ses identifiants de tâche et de vidéo, à sa clé d’objet, à sa somme de contrôle et à sa consommation déclarée.

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

Reprendre sans lancer un deuxième téléchargement

ProblèmeAction suivante
Délai de soumission dépassé ou identifiant de tâche non enregistréConservez job-001 et consultez History à l’aide de l’horodatage et de la vidéo. Ne supprimez pas ce dossier pour forcer une nouvelle soumission. Retrouvez la tâche d’origine avant de décider si une nouvelle requête est nécessaire.
pending / processingAttendez 10 secondes, puis relancez collect avec job-001. Il lit uniquement la tâche existante.
Tâche en échecInspectez l’erreur dans job-status.json. Corrigez la vidéo ou la configuration du stockage avant de lancer explicitement une nouvelle tâche dans un nouveau dossier et sous un nouveau préfixe.
401 / 403 / 402 / 429Vérifiez la clé, l’autorisation ou le solde. Pour 429, lisez Retry-After dans les en-têtes enregistrés et attendez. Les scripts ne retentent pas automatiquement la soumission.
Échec de récupération du résultat ou URL signée expiréeRelancez collect pour job-001 afin de redemander le résultat existant.
S3 AccessDeniedCorrigez l’identité AWS locale de lecture ou la politique du bucket. L’accès d’envoi de FlashData et l’accès de lecture local sont distincts.
Fichier partiel, chemin incorrect, taille ou MD5 différentConservez le relevé et le fichier pour les examiner. Après avoir résolu la cause, mettez media.mp4.part de côté puis relancez verify pour effectuer une nouvelle lecture S3. Ne relancez pas submit.