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

Référence API

API de traitement Bulk

Créez et pilotez des tâches YouTube à partir de fichiers, puis récupérez leurs manifestes et leurs fichiers de résultats.

Sur cette page

Bac à sable API

Choisissez une source et copiez un workflow Python ou Bash complet, une requête seule ou un exemple de réponse. Le bac à sable affiche le code sans soumettre de tâche. Les workflows complets gèrent l’envoi du fichier, le suivi de l’état et la récupération de toutes les parties du résultat.

Paramètres de la source

Configurer un workflow Bulk

Fichier local UTF-8 contenant un ID YouTube par ligne, dans la limite de 2 GiB. Format du fichier d’entrée.

Laissez ce champ vide pour essayer en-orig, puis en, et renvoyer une piste. Sinon, saisissez un code, ou jusqu’à 10 codes distincts séparés par des virgules.

Piste de sous-titres auto

Livraison des résultats

Laissez cette option désactivée pour récupérer les résultats via l’API FlashData.

Webhook de fin de traitement BulkNotification de publication du manifeste et vérification
POSThttps://api.flashdata.dev/v2/bulk-jobs
Python 3 · standard library
import gzip
import json
import os
from pathlib import Path
import random
import re
import shutil
import time
import urllib.error
import urllib.parse
import urllib.request

api_key = "YOUR_API_KEY"
api_url = "https://api.flashdata.dev/v2"
input_file = Path("video-ids.txt")
output_dir = Path("bulk-results")
bulk_id = ""  # Paste a saved Bulk ID to monitor/retrieve it without submitting again.
poll_timeout_seconds = 1800
payload = {
    "source": "youtube_captions",
    "options": {
        "auto": False,
    },
}

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(NoRedirect())
os.umask(0o077)

def api(path, method="GET", body=None):
    data = None if body is None else json.dumps(body).encode("utf-8")
    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
    for attempt in range(5):
        try:
            request = urllib.request.Request(api_url + path, data=data, headers=headers, method=method)
            with opener.open(request, timeout=60) as response:
                return json.load(response)
        except urllib.error.HTTPError as error:
            if method != "GET" or error.code not in (429, 502, 503, 504) or attempt == 4:
                raise
            retry_after = error.headers.get("Retry-After", "")
            delay = min(120, int(retry_after)) if retry_after.isdigit() else 2 ** attempt
            time.sleep(delay + random.random())

def result_location(path):
    request = urllib.request.Request(api_url + path, headers={"X-API-Key": api_key})
    try:
        with opener.open(request, timeout=60):
            raise RuntimeError("Expected a 302 result redirect")
    except urllib.error.HTTPError as error:
        if error.code != 302:
            raise
        location = error.headers.get("Location", "")
    parsed = urllib.parse.urlsplit(location)
    if parsed.scheme != urllib.parse.urlsplit(api_url).scheme or not parsed.hostname or parsed.username or parsed.password:
        raise RuntimeError("Invalid signed storage URL")
    return location

if not bulk_id:
    if not input_file.is_file() or not 1 <= input_file.stat().st_size <= 2147483648:
        raise ValueError("Use a nonempty UTF-8 ID file up to 2 GiB")
    created = api("/bulk-jobs", "POST", payload)
    bulk_id = created["job"]["id"]
    if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
        raise RuntimeError("Invalid Bulk ID")
    work = output_dir / bulk_id
    work.mkdir(parents=True, exist_ok=True)
    (work / "created.json").write_text(json.dumps(created, indent=2))
    print("Saved Bulk ID:", bulk_id, flush=True)
    upload = created["upload"]
    upload_url = urllib.parse.urlsplit(upload["href"])
    if upload["method"] != "PUT" or upload_url.scheme != urllib.parse.urlsplit(api_url).scheme or not upload_url.hostname or upload_url.username or upload_url.password:
        raise RuntimeError("Invalid signed upload URL")
    with input_file.open("rb") as file:
        request = urllib.request.Request(upload["href"], data=file, method="PUT", headers={
            "Content-Type": upload["contentType"], "Content-Length": str(input_file.stat().st_size)
        })
        with opener.open(request, timeout=120) as response:
            response.read()
    api("/bulk-jobs/" + bulk_id + "/start", "POST")

if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
    raise ValueError("Invalid Bulk ID")
work = output_dir / bulk_id
work.mkdir(parents=True, exist_ok=True)
deadline = time.monotonic() + poll_timeout_seconds
while True:
    job = api("/bulk-jobs/" + bulk_id)["job"]
    (work / "status.json").write_text(json.dumps(job, indent=2))
    print(job["status"], job["input"], job["counts"], flush=True)
    if job["status"] == "completed":
        break
    if job["status"] in ("paused", "failed", "cancelled", "awaiting_upload"):
        raise RuntimeError(json.dumps({"id": bulk_id, "status": job["status"], "pauseReason": job.get("pauseReason"), "error": job.get("error")}))
    if time.monotonic() >= deadline:
        raise TimeoutError("Job still running. Set bulk_id to " + bulk_id + " and rerun to continue monitoring.")
    time.sleep(10 + random.random())

manifest_url = result_location("/bulk-jobs/" + bulk_id + "/results")
with opener.open(manifest_url, timeout=60) as response:  # No API key sent to storage.
    manifest = json.load(response)
(work / "manifest.json").write_text(json.dumps(manifest, indent=2))
for part in manifest["parts"]:
    number = part["number"]
    if type(number) is not int or number < 1:
        raise RuntimeError("Invalid part number")
    path = "/bulk-jobs/" + bulk_id + "/results/" + str(number)
    if part["href"] != api_url + path:
        raise RuntimeError("Unexpected part API URL")
    storage_url = result_location(path)
    compressed = work / ("part-" + str(number) + ".jsonl.gz")
    with opener.open(storage_url, timeout=120) as response, compressed.open("wb") as file:
        shutil.copyfileobj(response, file, 1024 * 1024)
    with compressed.open("rb") as file:
        gzipped = file.read(2) == b"\x1f\x8b"
    reader = gzip.open(compressed, "rb") if gzipped else compressed.open("rb")
    with reader, (work / ("part-" + str(number) + ".jsonl")).open("wb") as file:
        shutil.copyfileobj(reader, file, 1024 * 1024)
print("Saved manifest and decoded NDJSON parts in", work)
Créer, envoyer, démarrer, suivre et récupérer toutes les partiesAuthentification X-API-Key

Endpoints

Tous les endpoints utilisent https://api.flashdata.dev/v2. Créer une tâche → envoyer un fichier d’ID vidéo → démarrer → suivre l’avancement → récupérer le manifeste et toutes les parties du résultat.

MéthodeCheminAction
POST/v2/bulk-jobsCréer une tâche Bulk
POST/v2/bulk-jobs/{bulkId}/startEnvoyer le fichier et démarrer
GET/v2/bulk-jobs/{bulkId}Consulter l’état d’une tâche
GET/v2/bulk-jobsLister les tâches
POST/v2/bulk-jobs/{bulkId}/pauseMettre une tâche en pause
PATCH/v2/bulk-jobs/{bulkId}Modifier les options d’une tâche
POST/v2/bulk-jobs/{bulkId}/resumeReprendre une tâche
DELETE/v2/bulk-jobs/{bulkId}Annuler une tâche
GET/v2/bulk-jobs/{bulkId}/resultsRécupérer le manifeste des résultats
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Télécharger les parties du résultat

Authentification et fichier d’entrée

Définissez FLASHDATA_API_KEY avec une clé autorisée à accéder à la source choisie. Utilisez la même clé et le même compte pour créer la tâche, la piloter et récupérer les résultats. Le traitement utilise le solde du compte et la tarification habituelle de chaque source. YouTube Download nécessite un accès rattaché à un compte propriétaire et options.storage.

Créez un dossier de travail bulk-api/ et exécutez les exemples depuis ce dossier. Le workflow Python complet du bac à sable utilise la bibliothèque standard de Python 3.10+. Les exemples Python de chaque endpoint ci-dessous nécessitent Requests ; les exemples cURL utilisent Bash, cURL 7.76+, jq et gzip. Choisissez un seul langage par action pour éviter de créer ou de démarrer deux fois le même traitement.

Le fichier d’entrée doit être encodé en UTF-8 et contenir un ID vidéo YouTube de 11 caractères par ligne, dans la limite de 2 GiB. Utilisez des ID, pas des URL. Supprimez les doublons avant l’envoi : chaque occurrence d’un ID est traitée séparément.

SourceOptions communes
youtube_metadatainclude_formats, include_chapters
youtube_transcriptlanguage, auto
youtube_captionslanguage, auto
youtube_trainabilityAucune option
youtube_downloadOptions médias et destination de stockage
Dépendance Python
python -m pip install requests

Champs de la requête de création

ChampTypeUtilisation
sourcestringObligatoire. Une même source prise en charge pour tous les ID du fichier.
optionsobjectOptions de la source appliquées à tous les ID. Les sources de données acceptent result_storage ; YouTube Download nécessite storage.
callback_urlstringURL HTTPS publique facultative pour le callback de fin de traitement. La notification est envoyée après la publication du manifeste.

Créer une tâche Bulk

Créez une tâche, envoyez à upload.href un fichier texte UTF-8 contenant un ID vidéo YouTube de 11 caractères par ligne, puis appelez start. La création de la tâche ne lance pas le traitement.

Cet exemple crée video-ids.txt et enregistre la réponse 201 dans bulk-created.json. Gardez ce fichier privé et réutilisez job.id pour chaque requête suivante. La tâche est créée à l’état awaiting_upload ; l’URL d’envoi expire après 15 minutes.

Endpoint
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Enregistrez bulk_create.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

bulk_create.py
import json
import os
from pathlib import Path

import requests

os.umask(0o077)
Path("video-ids.txt").write_bytes(b"jNQXAC9IVRw\ndQw4w9WgXcQ\n")
response = requests.post(
    "https://api.flashdata.dev/v2/bulk-jobs",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "youtube_metadata", "options": {"include_formats": False}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
receipt = response.json()
Path("bulk-created.json").write_text(json.dumps(receipt, indent=2), encoding="utf-8")
print(json.dumps(receipt["job"], indent=2))
Exécuter depuis bulk-api/
python bulk_create.py

Réponses et schéma de la requête

Code HTTPSignification
201Tâche Bulk créée avec une URL d’envoi direct valable 15 minutes
401Authentification requise ou invalide
422Échec de la validation de la requête
503Une dépendance ou un catalogue requis est temporairement indisponible
Corps de la requête
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Envoyer le fichier et démarrer

Lancez le traitement du fichier d’ID vidéo envoyé, encodé en UTF-8 et limité à 2 GiB (2147483648 octets). Ne modifiez pas ce fichier après le démarrage.

Envoyez d’abord video-ids.txt par PUT à l’URL upload.href de la réponse de création, avec upload.contentType et sans X-API-Key. L’exemple appelle start uniquement après la réussite de l’envoi. Ne modifiez plus le fichier envoyé.

ParamètreEmplacementConditions
bulkIdpathObligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Enregistrez bulk_start.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

bulk_start.py
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))
upload = receipt["upload"]
if upload["method"] != "PUT" or not upload["href"].startswith("https://"):
    raise ValueError("Expected an HTTPS PUT upload URL")
# Stream the file to storage without the FlashData key.
with open("video-ids.txt", "rb") as file:
    response = requests.put(
        upload["href"], data=file,
        headers={"Content-Type": upload["contentType"]},
        timeout=300, allow_redirects=False,
    )
    response.raise_for_status()
    if not 200 <= response.status_code < 300:
        raise RuntimeError("Upload did not complete; do not start the job yet")

bulk_id = receipt["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/start",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json()["job"], indent=2))
Exécuter depuis bulk-api/
python bulk_start.py

Réponses

Code HTTPSignification
200Tâche Bulk démarrée, ou état actuel en cas de répétition de la même requête
401Authentification requise ou invalide
404Ressource introuvable ou n’appartenant pas au compte appelant
409Conflit d’état de la ressource ou d’idempotence
422Échec de la validation de la requête
503Une dépendance ou un catalogue requis est temporairement indisponible
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Consulter l’état d’une tâche

Consultez job.status, input, counts, pauseReason et error. Interrogez le même ID en espaçant les requêtes. L’état completed indique que le manifeste est publié, pas que toutes les vidéos ont été traitées avec succès.

ParamètreEmplacementConditions
bulkIdpathObligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Enregistrez bulk_status.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

bulk_status.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("bulk-job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
Exécuter depuis bulk-api/
python bulk_status.py

Réponses

Code HTTPSignification
200État de la tâche Bulk
401Authentification requise ou invalide
404Ressource introuvable ou n’appartenant pas au compte appelant
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Lister les tâches

La réponse contient data et pagination. Utilisez pagination.nextCursor comme paramètre de requête cursor pour la page suivante, jusqu’à ce que sa valeur soit null. Le paramètre limit accepte de 1 à 50 éléments ; sa valeur par défaut est 20.

ParamètreEmplacementConditions
cursorqueryFacultatif · {"type":"string","maxLength":512}
limitqueryFacultatif · {"type":"integer","minimum":1,"maximum":50,"default":20}
Endpoint
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Enregistrez list_bulk_jobs.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

list_bulk_jobs.py
import json
import os
from pathlib import Path

import requests

response = requests.get(
    "https://api.flashdata.dev/v2/bulk-jobs?limit=20",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Exécuter depuis bulk-api/
python list_bulk_jobs.py

Réponses

Code HTTPSignification
200Page de résultats contenant les tâches Bulk
401Authentification requise ou invalide
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Mettre une tâche en pause

Mettez en pause les nouvelles soumissions et la préparation des fichiers de résultats. Les tâches existantes continuent avec leurs paramètres et leur tarification d’origine. Reprenez la tâche lorsque vous êtes prêt.

ParamètreEmplacementConditions
bulkIdpathObligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Enregistrez pause_bulk_job.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

pause_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/pause",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Exécuter depuis bulk-api/
python pause_bulk_job.py

Réponses

Code HTTPSignification
200Tâche Bulk mise en pause, ou état actuel en cas de répétition de la même requête
401Authentification requise ou invalide
404Ressource introuvable ou n’appartenant pas au compte appelant
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Modifier les options d’une tâche

Modifiez les options en attente d’envoi du fichier, ou pendant une pause avant la fin de la lecture du fichier d’entrée. Les tâches existantes conservent leurs paramètres. Si la mise en pause est encore en cours, attendez avant de réessayer après une réponse 409. Une fois toutes les entrées lues, seuls les identifiants de livraison peuvent être mis à jour. Définissez callback_url sur null pour supprimer le callback.

Cet exemple supprime le callback de fin de traitement. Pour modifier les paramètres de la source, envoyez plutôt un objet options. Mettez d’abord la tâche en pause et attendez que la pause soit effective ; une réponse 409 indique que la modification ne peut pas encore être appliquée. Les tâches enfants existantes conservent leurs options d’origine.

ParamètreEmplacementConditions
bulkIdpathObligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Enregistrez update_bulk_job.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

update_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.patch(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"callback_url": None},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Exécuter depuis bulk-api/
python update_bulk_job.py

Réponses et schéma de la requête

Code HTTPSignification
200État de la tâche Bulk après modification
401Authentification requise ou invalide
404Ressource introuvable ou n’appartenant pas au compte appelant
409Conflit d’état de la ressource ou d’idempotence
422Échec de la validation de la requête
Corps de la requête
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Reprendre une tâche

Corrigez d’abord la cause indiquée par pauseReason, par exemple en ajoutant des crédits ou en mettant à jour les identifiants de stockage, puis reprenez la tâche avec le même ID Bulk.

ParamètreEmplacementConditions
bulkIdpathObligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Enregistrez resume_bulk_job.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

resume_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/resume",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Exécuter depuis bulk-api/
python resume_bulk_job.py

Réponses

Code HTTPSignification
200État actuel de la tâche Bulk
401Authentification requise ou invalide
404Ressource introuvable ou n’appartenant pas au compte appelant
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Annuler une tâche

Arrêtez la soumission de nouvelles tâches. Les tâches existantes peuvent encore se terminer et être facturées au tarif habituel. Une tâche annulée ne publie pas de manifeste final.

ParamètreEmplacementConditions
bulkIdpathObligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Enregistrez cancel_bulk_job.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

cancel_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.delete(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Exécuter depuis bulk-api/
python cancel_bulk_job.py

Réponses

Code HTTPSignification
200État actuel de la tâche Bulk
401Authentification requise ou invalide
404Ressource introuvable ou n’appartenant pas au compte appelant
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Récupérer le manifeste des résultats

Suivez la redirection pour télécharger le manifeste JSON, puis utilisez ses liens pour récupérer les fichiers de résultats. Appelez les URL signées du stockage sans votre clé API. Les résultats restent disponibles pendant 24 heures après la fin de l’ensemble de la tâche Bulk.

La requête API authentifiée renvoie 302 avec un en-tête Location. Récupérez cette URL HTTPS de stockage dans une requête distincte, sans X-API-Key. L’exemple enregistre manifest.json. Le code 409 indique que les résultats ne sont pas prêts ; 410 indique qu’ils ont expiré.

ParamètreEmplacementConditions
bulkIdpathObligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Enregistrez bulk_manifest.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

bulk_manifest.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a manifest redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

manifest = requests.get(url, timeout=120)  # No FlashData API key.
manifest.raise_for_status()
Path("manifest.json").write_text(json.dumps(manifest.json(), indent=2), encoding="utf-8")
print(json.dumps(manifest.json(), indent=2))
Exécuter depuis bulk-api/
python bulk_manifest.py

Réponses

Code HTTPSignification
200Manifeste JSON téléchargé après la redirection
302Redirection vers une URL privée R2 à durée de validité limitée ; ne transmettez pas les identifiants API à cette URL · Location
401Authentification requise ou invalide
404Ressource introuvable ou n’appartenant pas au compte appelant
409Conflit d’état de la ressource ou d’idempotence
410La période de conservation du résultat a expiré
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Télécharger les parties du résultat

Utilisez chaque parts[].number de manifest.json. Chaque endpoint renvoie une redirection 302 vers un fichier NDJSON compressé avec gzip. Téléchargez-le sans clé API, décompressez-le, puis analysez un objet JSON par ligne. Rapprochez les résultats des entrées à l’aide du champ index, qui commence à zéro. L’exemple récupère toutes les parties et conserve les fichiers .ndjson.gz et .ndjson.

ParamètreEmplacementConditions
bulkIdpathObligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathObligatoire · {"type":"integer","minimum":0}
Endpoint
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Enregistrez bulk_parts.py dans bulk-api/, à côté de bulk-created.json. Copiez le script complet, puis exécutez la commande affichée en dessous.

bulk_parts.py
import json
import os
from pathlib import Path

import requests
import gzip
import shutil

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
manifest = json.loads(Path("manifest.json").read_text(encoding="utf-8"))
for part in manifest["parts"]:
    number = part["number"]
    response = requests.get(
        f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results/{number}",
        headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
        timeout=30, allow_redirects=False,
    )
    response.raise_for_status()
    if response.status_code != 302:
        raise RuntimeError(f"Expected a part redirect, got {response.status_code}")
    url = response.headers["Location"]
    if not url.startswith("https://"):
        raise ValueError("Expected an HTTPS storage URL")

    # Save the original gzip bytes; do not decompress twice.
    with requests.get(url, stream=True, timeout=120) as download:
        download.raise_for_status()
        with open(f"part-{number}.ndjson.gz", "wb") as file:
            download.raw.decode_content = False
            shutil.copyfileobj(download.raw, file)
    with gzip.open(f"part-{number}.ndjson.gz", "rt", encoding="utf-8") as rows:
        with open(f"part-{number}.ndjson", "w", encoding="utf-8") as file:
            for line in rows:
                file.write(line)
                print(json.dumps(json.loads(line)))
Exécuter depuis bulk-api/
python bulk_parts.py

Réponses

Code HTTPSignification
200Fichier NDJSON compressé avec gzip, téléchargé après la redirection
302Redirection vers une URL privée R2 à durée de validité limitée ; ne transmettez pas les identifiants API à cette URL · Location
401Authentification requise ou invalide
404Ressource introuvable ou n’appartenant pas au compte appelant
409Conflit d’état de la ressource ou d’idempotence
410La période de conservation du résultat a expiré
200 · application/x-ndjson
{
  "type": "string"
}

États des tâches et conservation des résultats

Les résultats restent disponibles pendant 24 heures après la fin de l’ensemble de la tâche Bulk. Enregistrez-les avant expiresAt. Les médias livrés dans votre stockage suivent la politique de conservation de votre bucket. Une tâche completed peut contenir des vidéos en échec ; counts.invalid compte les lignes d’entrée rejetées.

ÉtatAction suivante
awaiting_uploadEnvoyez le fichier, puis appelez start.
runningInterrogez le même ID avec un délai croissant entre les requêtes. Le champ input.complete indique si la lecture du fichier est terminée.
pausedConsultez pauseReason, corrigez la cause, puis reprenez la tâche.
finalizingAttendez la préparation des fichiers de résultats et la publication du manifeste.
completedTéléchargez le manifeste et toutes les parties du résultat. Vérifiez status et error pour chaque ligne.
failed / cancelledConsultez error et l’état enregistré. Aucun manifeste final n’est publié.

Livraison dans votre stockage

Utilisez le bac à sable pour configurer un fournisseur et afficher les champs exacts de la requête. Placez vos identifiants de stockage dans l’objet de stockage choisi. X-API-Key authentifie uniquement les requêtes à l’API FlashData.

SourceChamp de la requête de créationLivraison
Métadonnées, transcription, sous-titres, vérification de licenceoptions.result_storageFacultatif. Copie les parties du résultat NDJSON et un manifeste dans votre bucket.
youtube_downloadoptions.storageObligatoire. Livre les médias dans votre bucket ; result_storage et browser_delivery ne sont pas acceptés.

Retrouver les fichiers livrés

Le manifeste de données est écrit en dernier. Il liste les clés des objets, leur taille et leur somme de contrôle SHA-256. Il diffère du manifeste FlashData, qui contient des valeurs href vers l’API. Dans les chemins des données, YYYYMMDD correspond à la date UTC de création de la tâche Bulk ; dans les chemins des médias, à la date UTC d’envoi de chaque vidéo vers le stockage. La livraison de données Bulk vers OSS nécessite un endpoint aliyuncs.com.

Pour accéder aux valeurs file_url de médias privés, utilisez le SDK de votre stockage ou une URL signée par ce fournisseur. Une clé FlashData ne donne pas accès au bucket. Les éventuels fichiers de métadonnées sont placés à côté des médias. Le champ delivery.retryCount indique le nombre de nouvelles tentatives de livraison.

Organisation des objets de données
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Recevoir un webhook de fin de traitement

Placez callback_url, une URL HTTPS publique, en dehors de l’objet options. Bulk envoie completed uniquement après la publication du manifeste. Aucun événement n’est envoyé pour chaque vidéo, ni à la fin d’une tâche failed ou cancelled. Conservez l’interrogation de l’état comme solution de secours.

  1. Enregistrez delivery_id pour dédupliquer les événements, puis renvoyez rapidement une réponse 2xx. La livraison peut être retentée jusqu’à huit fois, avec un délai croissant entre les tentatives.
  2. Les événements ne sont pas signés. Vérifiez que id et source correspondent à la réponse de création enregistrée. Confirmez l’état completed auprès de l’API de gestion authentifiée avant de planifier la récupération des résultats. Ignorez les URL d’un événement non vérifié.
Requête de création avec callback
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Exemple d’événement de fin de traitement
{
  "delivery_id": "bulk-completion:bulk_EXAMPLE123",
  "id": "bulk_EXAMPLE123",
  "source": "youtube_metadata",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123/results",
      "method": "GET"
    }
  ]
}

Définitions des schémas

BulkJobCreated

BulkJobCreated
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job",
    "upload"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    },
    "upload": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "href",
        "method",
        "expiresAt",
        "contentType"
      ],
      "properties": {
        "href": {
          "type": "string",
          "format": "uri"
        },
        "method": {
          "type": "string",
          "const": "PUT"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "contentType": {
          "type": "string",
          "const": "text/plain; charset=utf-8"
        }
      }
    }
  }
}

BulkJob

BulkJob
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "source",
    "status",
    "input",
    "counts",
    "delivery",
    "pauseReason",
    "error",
    "createdAt",
    "startedAt",
    "completedAt",
    "expiresAt",
    "links"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^bulk_[A-Za-z0-9_-]{8,}$"
    },
    "source": {
      "type": "string",
      "enum": [
        "youtube_metadata",
        "youtube_transcript",
        "youtube_captions",
        "youtube_trainability",
        "youtube_download"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "awaiting_upload",
        "running",
        "paused",
        "finalizing",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "bytes",
        "complete",
        "scannedBytes",
        "scannedLines"
      ],
      "properties": {
        "bytes": {
          "type": "integer",
          "minimum": 0
        },
        "complete": {
          "type": "boolean"
        },
        "scannedBytes": {
          "type": "integer",
          "minimum": 0
        },
        "scannedLines": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "counts": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "accepted",
        "completed",
        "failed",
        "invalid",
        "results"
      ],
      "properties": {
        "accepted": {
          "type": "integer",
          "minimum": 0
        },
        "completed": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        },
        "invalid": {
          "type": "integer",
          "minimum": 0
        },
        "results": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "pauseReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "delivery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "customerStorage",
        "storageType",
        "uploadedParts",
        "retryCount"
      ],
      "properties": {
        "customerStorage": {
          "type": "boolean"
        },
        "storageType": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "s3",
            "s3_compatible",
            "oss",
            "gcs",
            "azure",
            "cos",
            "bos",
            "tos",
            null
          ]
        },
        "uploadedParts": {
          "type": "integer",
          "minimum": 0
        },
        "retryCount": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "error": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "code",
            "detail"
          ],
          "properties": {
            "code": {
              "type": "string"
            },
            "detail": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "startedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "completedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "links": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JobLink"
      }
    }
  }
}

BulkJobPage

BulkJobPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BulkJob"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

BulkJobResponse

BulkJobResponse
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    }
  }
}

CreateBulkJobRequest

CreateBulkJobRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "source"
  ],
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "youtube_metadata",
        "youtube_transcript",
        "youtube_captions",
        "youtube_trainability",
        "youtube_download"
      ]
    },
    "options": {
      "type": "object",
      "additionalProperties": true,
      "description": "Reused for every ID. Metadata accepts include_formats and include_chapters. Transcript and captions accept language (one code or an array of 1–10 distinct codes) and auto (applies to all requested languages). Omit language to prefer en-orig, fall back to en, and return one track. With auto=true, each requested code tries its -orig track first, then the plain code. Explicit -orig codes and auto=false stay exact. languageCode identifies the selected track; requestedLanguageCode is included when it differs from the requested code. A language array returns tracks and per-language errors for each video with at least one retrieved track. If no track is retrieved, the video job fails and its reserved credits are refunded. Bulk exports use one JSONL record per video. Trainability accepts no source options. These four data sources optionally accept result_storage. Supported storage_type values are s3, s3_compatible, oss, gcs, azure, cos, bos, and tos. storage_url is the bucket name (Azure container name); object_prefix is optional. S3, S3-compatible, OSS, COS, BOS, and TOS use access_key and secret_key. S3-compatible and OSS also require a public HTTPS endpoint_url. COS, BOS, and TOS require region and use fixed provider endpoints. COS bucket names include the APPID. BOS S3-compatible HTTPS delivery supports bj, su, and hkg. GCS requires service_account with project_id, client_email, and private_key. Azure requires account_name and a container SAS sas_token with write permission. Default object_prefix is YYYYMMDD, frozen to the UTC bulk creation date. Files are written to <prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz; manifest.json in the same bulk directory is written last. Each JSONL row includes its input index and completed, failed, or invalid status. Internal R2 results remain available through the result links for 24 hours. Download accepts the normal YouTube download parameters, requires customer storage, and does not permit browser_delivery. Download storage supports the same eight provider types and credential shapes listed above under the storage field. Download storage may include object_prefix; YYYYMMDD tokens resolve to the UTC upload date, while literal prefixes are unchanged."
    },
    "callback_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "Optional public HTTPS endpoint notified once after manifest publication."
    }
  }
}

JobLink

JobLink
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "rel",
    "href",
    "method"
  ],
  "properties": {
    "rel": {
      "type": "string",
      "enum": [
        "self",
        "results",
        "content",
        "download"
      ]
    },
    "href": {
      "type": "string",
      "format": "uri"
    },
    "method": {
      "type": "string",
      "const": "GET"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "filename": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "size_bytes": {
      "type": "integer",
      "minimum": 1
    }
  }
}

Pagination

Pagination
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "hasMore",
    "limit"
  ],
  "properties": {
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "previousCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "hasMore": {
      "type": "boolean"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

Problem

Problem
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "type",
    "title",
    "status",
    "code",
    "requestId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri-reference"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "code": {
      "type": "string",
      "pattern": "^[a-z0-9_]+$"
    },
    "detail": {
      "type": "string"
    },
    "requestId": {
      "type": "string",
      "pattern": "^req_"
    },
    "fieldErrors": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/FieldError"
      }
    }
  }
}

FieldError

FieldError
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "field",
    "code",
    "message"
  ],
  "properties": {
    "field": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

UpdateBulkJobRequest

UpdateBulkJobRequest
{
  "type": "object",
  "additionalProperties": false,
  "minProperties": 1,
  "properties": {
    "options": {
      "type": "object",
      "additionalProperties": true,
      "description": "Partial option update. Nested storage fields are merged so unchanged credentials do not need to be resent. Data result_storage fields are merged the same way. After all IDs have been scanned, a paused data bulk job accepts credential updates only: access_key and secret_key, GCS service_account, or Azure sas_token, depending on the storage type. The complete merged configuration is validated before it is stored."
    },
    "callback_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "maxLength": 2048,
      "description": "Replacement completion callback, or null to remove the callback."
    }
  }
}