Parcourir la documentation
Référence API
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.
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.
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 Bulk
Notification de publication du manifeste et vérificationhttps://api.flashdata.dev/v2/bulk-jobsEndpoints
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éthode | Chemin | Action |
|---|---|---|
| POST | /v2/bulk-jobs | Créer une tâche Bulk |
| POST | /v2/bulk-jobs/{bulkId}/start | Envoyer le fichier et démarrer |
| GET | /v2/bulk-jobs/{bulkId} | Consulter l’état d’une tâche |
| GET | /v2/bulk-jobs | Lister les tâches |
| POST | /v2/bulk-jobs/{bulkId}/pause | Mettre une tâche en pause |
| PATCH | /v2/bulk-jobs/{bulkId} | Modifier les options d’une tâche |
| POST | /v2/bulk-jobs/{bulkId}/resume | Reprendre une tâche |
| DELETE | /v2/bulk-jobs/{bulkId} | Annuler une tâche |
| GET | /v2/bulk-jobs/{bulkId}/results | Ré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.
| Source | Options communes |
|---|---|
| youtube_metadata | include_formats, include_chapters |
| youtube_transcript | language, auto |
| youtube_captions | language, auto |
| youtube_trainability | Aucune option |
| youtube_download | Options médias et destination de stockage |
python -m pip install requestsChamps de la requête de création
| Champ | Type | Utilisation |
|---|---|---|
| source | string | Obligatoire. Une même source prise en charge pour tous les ID du fichier. |
| options | object | Options de la source appliquées à tous les ID. Les sources de données acceptent result_storage ; YouTube Download nécessite storage. |
| callback_url | string | URL 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.
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python bulk_create.pyumask 077
printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
curl --fail-with-body --silent --show-error \
'https://api.flashdata.dev/v2/bulk-jobs' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{"source":"youtube_metadata","options":{"include_formats":false}}' \
--output bulk-created.json &&
jq '.job | {id, source, status}' bulk-created.jsonRéponses et schéma de la requête
| Code HTTP | Signification |
|---|---|
| 201 | Tâche Bulk créée avec une URL d’envoi direct valable 15 minutes |
| 401 | Authentification requise ou invalide |
| 422 | Échec de la validation de la requête |
| 503 | Une dépendance ou un catalogue requis est temporairement indisponible |
{
"$ref": "#/components/schemas/CreateBulkJobRequest"
}{
"$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ètre | Emplacement | Conditions |
|---|---|---|
| bulkId | path | Obligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python bulk_start.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
UPLOAD_URL=$(jq -er '.upload.href' bulk-created.json)
CONTENT_TYPE=$(jq -er '.upload.contentType' bulk-created.json)
curl --fail-with-body --silent --show-error --proto '=https' \
--header "Content-Type: $CONTENT_TYPE" \
--upload-file video-ids.txt "$UPLOAD_URL" &&
curl --fail-with-body --silent --show-error --request POST \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/start" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}"Réponses
| Code HTTP | Signification |
|---|---|
| 200 | Tâche Bulk démarrée, ou état actuel en cas de répétition de la même requête |
| 401 | Authentification requise ou invalide |
| 404 | Ressource introuvable ou n’appartenant pas au compte appelant |
| 409 | Conflit d’état de la ressource ou d’idempotence |
| 422 | Échec de la validation de la requête |
| 503 | Une dépendance ou un catalogue requis est temporairement indisponible |
{
"$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ètre | Emplacement | Conditions |
|---|---|---|
| bulkId | path | Obligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python bulk_status.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output bulk-job.json &&
jq '.job | {id, status, counts, pauseReason, error, expiresAt}' bulk-job.jsonRéponses
| Code HTTP | Signification |
|---|---|
| 200 | État de la tâche Bulk |
| 401 | Authentification requise ou invalide |
| 404 | Ressource introuvable ou n’appartenant pas au compte appelant |
{
"$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ètre | Emplacement | Conditions |
|---|---|---|
| cursor | query | Facultatif · {"type":"string","maxLength":512} |
| limit | query | Facultatif · {"type":"integer","minimum":1,"maximum":50,"default":20} |
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python list_bulk_jobs.pycurl --fail-with-body --silent --show-error --max-time 30 \
--request GET \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs?limit=20"Réponses
| Code HTTP | Signification |
|---|---|
| 200 | Page de résultats contenant les tâches Bulk |
| 401 | Authentification requise ou invalide |
{
"$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ètre | Emplacement | Conditions |
|---|---|---|
| bulkId | path | Obligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python pause_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request POST \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/pause"Réponses
| Code HTTP | Signification |
|---|---|
| 200 | Tâche Bulk mise en pause, ou état actuel en cas de répétition de la même requête |
| 401 | Authentification requise ou invalide |
| 404 | Ressource introuvable ou n’appartenant pas au compte appelant |
{
"$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ètre | Emplacement | Conditions |
|---|---|---|
| bulkId | path | Obligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python update_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request PATCH \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' --data '{"callback_url":null}' \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID"Réponses et schéma de la requête
| Code HTTP | Signification |
|---|---|
| 200 | État de la tâche Bulk après modification |
| 401 | Authentification requise ou invalide |
| 404 | Ressource introuvable ou n’appartenant pas au compte appelant |
| 409 | Conflit d’état de la ressource ou d’idempotence |
| 422 | Échec de la validation de la requête |
{
"$ref": "#/components/schemas/UpdateBulkJobRequest"
}{
"$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ètre | Emplacement | Conditions |
|---|---|---|
| bulkId | path | Obligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python resume_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request POST \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/resume"Réponses
| Code HTTP | Signification |
|---|---|
| 200 | État actuel de la tâche Bulk |
| 401 | Authentification requise ou invalide |
| 404 | Ressource introuvable ou n’appartenant pas au compte appelant |
{
"$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ètre | Emplacement | Conditions |
|---|---|---|
| bulkId | path | Obligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python cancel_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request DELETE \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID"Réponses
| Code HTTP | Signification |
|---|---|
| 200 | État actuel de la tâche Bulk |
| 401 | Authentification requise ou invalide |
| 404 | Ressource introuvable ou n’appartenant pas au compte appelant |
{
"$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ètre | Emplacement | Conditions |
|---|---|---|
| bulkId | path | Obligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEYEnregistrez 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.
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))python bulk_manifest.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
# Only send the API key to FlashData; fetch storage URLs separately.
fetch_bulk_result() {
local storage_url
storage_url=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/results$1" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') || return
curl --fail-with-body --silent --show-error --proto '=https' \
"${storage_url:?Expected a signed result URL}" --output "$2"
}
fetch_bulk_result '' manifest.json &&
jq '{status, counts, parts, expires_at}' manifest.jsonRéponses
| Code HTTP | Signification |
|---|---|
| 200 | Manifeste JSON téléchargé après la redirection |
| 302 | Redirection vers une URL privée R2 à durée de validité limitée ; ne transmettez pas les identifiants API à cette URL · Location |
| 401 | Authentification requise ou invalide |
| 404 | Ressource introuvable ou n’appartenant pas au compte appelant |
| 409 | Conflit d’état de la ressource ou d’idempotence |
| 410 | La période de conservation du résultat a expiré |
{
"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ètre | Emplacement | Conditions |
|---|---|---|
| bulkId | path | Obligatoire · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
| partNumber | path | Obligatoire · {"type":"integer","minimum":0} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEYEnregistrez 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.
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)))python bulk_parts.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
# Only send the API key to FlashData; fetch storage URLs separately.
fetch_bulk_result() {
local storage_url
storage_url=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/results$1" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') || return
curl --fail-with-body --silent --show-error --proto '=https' \
"${storage_url:?Expected a signed result URL}" --output "$2"
}
fetch_bulk_result '' manifest.json &&
jq '{status, counts, parts, expires_at}' manifest.json
# Run in the same Bash session as fetch_bulk_result.
jq -r '.parts[].number' manifest.json | while IFS= read -r PART; do
fetch_bulk_result "/$PART" "part-$PART.ndjson.gz" || exit
gzip -dc "part-$PART.ndjson.gz" > "part-$PART.ndjson" || exit
jq -c '{index, video_id, status, results, error}' "part-$PART.ndjson"
doneRéponses
| Code HTTP | Signification |
|---|---|
| 200 | Fichier NDJSON compressé avec gzip, téléchargé après la redirection |
| 302 | Redirection vers une URL privée R2 à durée de validité limitée ; ne transmettez pas les identifiants API à cette URL · Location |
| 401 | Authentification requise ou invalide |
| 404 | Ressource introuvable ou n’appartenant pas au compte appelant |
| 409 | Conflit d’état de la ressource ou d’idempotence |
| 410 | La période de conservation du résultat a expiré |
{
"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.
| État | Action suivante |
|---|---|
| awaiting_upload | Envoyez le fichier, puis appelez start. |
| running | Interrogez 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. |
| paused | Consultez pauseReason, corrigez la cause, puis reprenez la tâche. |
| finalizing | Attendez la préparation des fichiers de résultats et la publication du manifeste. |
| completed | Téléchargez le manifeste et toutes les parties du résultat. Vérifiez status et error pour chaque ligne. |
| failed / cancelled | Consultez 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.
| Source | Champ de la requête de création | Livraison |
|---|---|---|
| Métadonnées, transcription, sous-titres, vérification de licence | options.result_storage | Facultatif. Copie les parties du résultat NDJSON et un manifeste dans votre bucket. |
| youtube_download | options.storage | Obligatoire. 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.
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.jsonRecevoir 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.
- 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.
- 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é.
{
"source": "youtube_metadata",
"options": {
"include_formats": false,
"include_chapters": false
},
"callback_url": "https://your-app.example/webhooks/flashdata"
}{
"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
{
"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
{
"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
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BulkJob"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}BulkJobResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"job"
],
"properties": {
"job": {
"$ref": "#/components/schemas/BulkJob"
}
}
}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
{
"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
{
"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
{
"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
{
"type": "object",
"additionalProperties": false,
"required": [
"field",
"code",
"message"
],
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}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."
}
}
}