Parcourir la documentation
Référence API
API de sous-titres YouTube
Récupérez les sous-titres YouTube sous forme de texte horodaté et de transcription intégrale. Les sous-titres fournis par l’auteur de la vidéo sont sélectionnés par défaut.
Préparer une requête
L’identifiant à 11 caractères de l’URL de la vidéo, et non l’URL complète.
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.
https://data.flashdata.dev/v1/queries/realtimeParamètres
Envoyez source et video_id à la racine de l’objet JSON. Placez les options de la source dans params. Vous pouvez omettre les champs facultatifs.
Corps de la requête
sourcestring / Obligatoire- Définissez ce champ sur youtube_captions.
video_idstring / Obligatoire- Identifiant YouTube de la vidéo, composé de 11 caractères, par exemple FUfGcZ092b0. Les lettres, chiffres, tirets bas et traits d’union sont acceptés.Exactement 11 caractèresPar défaut :
Non définiFormat accepté
^[A-Za-z0-9_-]{11}$ paramsobject / Facultatif- Paramètres de cette requête.Par défaut :
{} callback_urlstring · nullable / Facultatif- Async et Batch uniquement. URL HTTPS publique de notification sur le port 443, de 2 048 caractères maximum, sans identifiants ni fragment. Omettez ce champ, ou utilisez null ou une chaîne vide pour désactiver les notifications. Dans un Batch, définissez-le pour chaque requête, en dehors de params.Par défaut :
Non défini
Sélection des sous-titres
params.languagestring | array / Facultatif- Omettez ce champ pour l’anglais : en-orig est essayé avant en. Avec auto=true, chaque code essaie d’abord sa piste -orig, puis le code demandé. Les codes -orig explicites et auto=false imposent une correspondance exacte. Un tableau demande de 1 à 10 langues distinctes.Par défaut :
en-orig → en params.autoboolean / Facultatif- true sélectionne les sous-titres générés par YouTube ; false sélectionne ceux fournis par l’auteur de la vidéo. Ce champ choisit l’origine des sous-titres ; il ne déclenche ni détection de langue ni nouvelle transcription.
trueoufalsePar défaut :false
Réponse
Le mode temps réel renvoie status: done. Lisez le résultat de la source dans results[0]; usage.credits indique les crédits facturés.
Lisez segments pour le texte des sous-titres avec les temps start/end en secondes, et fullText pour le texte complet. languageCode et isAutoGenerated décrivent la piste sélectionnée.
Lire le résultat
Enregistrez la réponse JSON d’une requête réussie dans response.json. Enregistrez le script ci-dessous dans read-response.py, dans le même dossier, puis exécutez python read-response.py. Il utilise uniquement la bibliothèque standard de Python et n’envoie aucune nouvelle requête.
import json
from pathlib import Path
response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
print("[]")
raise SystemExit(0)
result = response["results"][0]
output = {
"tracks": result.get("tracks", [result]),
"errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))Omettez language pour essayer en-orig, puis en, et renvoyer une seule piste. Avec auto=true, chaque code demandé essaie sa piste -orig avant le code sans suffixe ; un code -orig explicite ou auto=false impose une correspondance exacte. Les tableaux essaient toutes les langues demandées et renvoient tracks et errors dans l’ordre de la requête. languageCode identifie la piste sélectionnée ; requestedLanguageCode est présent lorsque le code demandé diffère de languageCode.
Pour les listes de langues, consultez errors pour repérer les pistes en échec. Si aucune piste n’est récupérée, la requête échoue et les crédits réservés sont remboursés. Un échec de l’extraction vidéo ou l’expiration du délai fait aussi échouer la requête.
auto vaut false par défaut pour sélectionner les sous-titres fournis par l’auteur de la vidéo. Utilisez true pour les sous-titres automatiques. L’API ne bascule jamais entre ces deux origines.
L’API lit les sous-titres YouTube existants ; elle ne génère pas de nouvelles transcriptions. La réponse par défaut contient des segments normalisés en JSON. Accept permet de sélectionner le texte brut et X-Respond-With: markdown sélectionne Markdown. languageName peut valoir null ; les horodatages des segments sont conservés.
Plusieurs langues
Envoyez un tableau de langues pour recevoir tracks et errors par langue. Cet exemple présente une piste anglaise disponible et une piste espagnole indisponible.
{
"source": "youtube_captions",
"video_id": "jNQXAC9IVRw",
"params": {
"language": [
"en",
"es"
],
"auto": false
}
}{
"videoId": "jNQXAC9IVRw",
"isAutoGenerated": false,
"tracks": [
{
"videoId": "jNQXAC9IVRw",
"languageCode": "en",
"languageName": null,
"isAutoGenerated": false,
"segments": [
{
"start": 0,
"end": 1.5,
"text": "Hello world."
}
],
"fullText": "Hello world."
}
],
"errors": [
{
"languageCode": "es",
"code": "language_unavailable",
"message": "Uploader-provided subtitles not available for language: es"
}
]
}Tous les champs de réponse
| Champ | Description |
|---|---|
sourcestring | Source API demandée. |
statusstring | done lorsque la requête realtime réussit. |
created_atstring | Date et heure de création de la réponse au format ISO 8601. |
usage.creditsnumber | Crédits facturés pour la requête selon votre offre. |
results[0].videoIdstring | Identifiant de la vidéo demandée. |
results[0].languageCodestring | Code de la piste de sous-titres effectivement sélectionnée, par exemple en-orig. |
results[0].languageNamestring · nullable | Nom de la langue, lorsqu’il est disponible. |
results[0].requestedLanguageCodestring · optional | Code demandé lorsqu’il diffère de languageCode, par exemple en si en-orig a été sélectionné. |
results[0].isAutoGeneratedboolean | Indique si les sous-titres sélectionnés ont été générés automatiquement. |
results[0].segmentsarray | Segments de sous-titres dans l’ordre chronologique. |
results[0].segments[].startnumber | Début du segment en secondes. |
results[0].segments[].endnumber | Fin du segment en secondes. |
results[0].segments[].textstring | Texte du sous-titre. |
results[0].fullTextstring | Texte de tous les segments assemblé en une transcription. |
results[0].tracksarray · optional | Pour les tableaux de langues uniquement. Pistes disponibles dans l’ordre de la requête ; chacune contient les champs de la réponse à une seule piste décrits ci-dessus. |
results[0].errorsarray · optional | Pour les tableaux de langues uniquement. Langues en échec dans l’ordre de la requête. Tableau vide si toutes les pistes sont récupérées. |
results[0].errors[].languageCodestring | Langue demandée pour laquelle la récupération a échoué. |
results[0].errors[].codestring | language_unavailable si la piste sélectionnée n’existe pas ; retrieval_failed si elle n’a pas pu être téléchargée ou analysée. |
results[0].errors[].messagestring | Description de l’erreur pour cette langue. |
Les champs ci-dessus décrivent la réponse JSON par défaut. Formats JSON, texte brut et Markdown.
Async renvoie un reçu de tâche ; Batch en renvoie un par identifiant vidéo. Vérifiez l’état de chaque tâche et récupérez ses résultats à l’aide des liens renvoyés.
Cycle de traitement Async et Batch
La soumission renvoie un reçu, pas les résultats. Async crée une tâche ; Batch renvoie une tâche distincte dans queries[] pour chaque requête acceptée. Suivez chaque tâche et récupérez ses résultats séparément.
Soumettez les requêtes à data.flashdata.dev ; lisez l’état et les résultats sur api.flashdata.dev avec la même clé X-API-Key. Les exemples liés dans les bases de l’API utilisent Python et cURL.
1. Enregistrer les identifiants de tâche
Conservez les champs de requête de cette source en passant à Async. Pour Batch, placez chaque requête dans le tableau queries d’un objet JSON. Enregistrez tous les identifiants de tâche renvoyés.
Requête Async et reçu de soumission · Corps de requête Batch
2. Vérifier l’état
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: attendez entre les vérifications et respectezRetry-Afterlorsqu’il est présent.completed: récupérez les résultats.failed: consultezjob.error.Lisez job.status, et non le champ status du reçu de soumission.
Vérifier l’état · Python et cURL
Référence API : état d’une tâche3. Récupérer les résultats
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsAprès la fin du traitement, authentifiez la requête de lecture du résultat, puis récupérez l’URL de stockage renvoyée par la redirection 302, sans votre clé API. Enregistrez le JSON dans les 24 heures suivant la fin du traitement.
Récupérer les résultats · Python et cURL · Formats de réponse
Référence API : récupération des résultats
La vérification de l’état et la récupération de résultats existants ne consomment aucun crédit de requête. Un délai de vérification dépassé n’annule pas la tâche : conservez son identifiant pour éviter de soumettre des doublons facturables. Codes d’erreur et nouvelles tentatives.
Webhooks de fin de tâche
Configurer chaque requête
Définissez callback_url à la racine d’une requête Async, ou dans chaque requête d’un Batch, en dehors de params. Aucune requête distincte d’enregistrement de webhook n’est nécessaire. Les requêtes Realtime n’envoient pas de notifications.
Utilisez une URL HTTPS publique sur le port 443. FlashData envoie une notification POST pour chaque tâche atteignant l’état completed ou failed ; l’événement contient des liens, pas le résultat lui-même.
Accuser réception et vérifier
Renvoyez 2xx après avoir enregistré durablement l’événement. Dédupliquez à l’aide de delivery_id, également envoyé dans X-Delivery-Id. Les redirections ne sont pas suivies.
Les envois en échec sont retentés avec un délai exponentiel, dans la limite de 8 tentatives au total et au plus tard 24 heures après la fin du traitement. Conservez la vérification périodique de l’état comme solution de secours.
Les notifications ne sont pas signées. Vérifiez l’identifiant, la source et l’état final de la tâche via l’endpoint d’état authentifié avant de traiter la notification. L’identifiant d’envoi sert à la déduplication ; il ne prouve pas l’authenticité.
Exemple d’événement webhook et ses champs
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_captions",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| Champ | Description |
|---|---|
delivery_idstring | Identifiant de livraison stable. Utilisez-le pour dédupliquer les notifications ; il est aussi envoyé dans l’en-tête X-Delivery-Id. |
idstring | Identifiant de la tâche. |
sourcestring | Source de données demandée. |
statusstring | completed ou failed. |
linksarray | Liens vers l’état et les résultats. Les notifications ne contiennent ni les résultats ni de clé API. |
links[].relstring | self ou results. |
links[].hrefstring | URL absolue de l’API de gestion ; authentifiez la requête avec votre clé API. |
links[].methodstring | GET. |
Traitement de fichiers Bulk
Importez un fichier contenant un identifiant vidéo par ligne et créez la tâche Bulk avec source : youtube_captions. Les options communes s’appliquent à tous les identifiants du fichier.
Options de la source : language, auto. Placez-les dans options à la création de la tâche Bulk.
Récupérez l’ensemble terminé sous forme de manifeste et de fichiers de résultats NDJSON compressés avec gzip. Pour les sources de données, définissez options.result_storage à la création de la tâche Bulk pour livrer aussi les fichiers de résultats dans votre stockage cloud. Enregistrez le manifeste et les fichiers de résultats dans les 24 heures suivant la fin de la tâche Bulk entière.
API de traitement Bulk · Python et cURL · Requêtes JSON Batch
Préparer un traitement Bulk pour cette source · Mettre en pause, reprendre et résoudre les erreurs
Résoudre les erreurs
Une vidéo peut disposer de sous-titres automatiques sans piste fournie par l’auteur, ou ne pas proposer la langue demandée. Vérifiez les sous-titres disponibles avec l’API de métadonnées, puis choisissez la langue et l’origine avant une nouvelle soumission.
Vérifier les langues de sous-titres disponibles avec l’API de métadonnées. Une nouvelle requête consomme des crédits ; changer de piste ne modifie pas une tâche existante.
Pour les erreurs d’authentification, de solde, de format de requête ou de limite de débit, consultez la référence commune des erreurs. Une soumission ayant dépassé le délai d’attente peut tout de même avoir créé une tâche ; vérifiez les tâches existantes avant de réessayer.
Erreurs et codes d’état · Quand réessayer · Limites de débit
Guide étape par étape : Récupérer des sous-titres horodatés
Tarifs
| Plans | Tarifs d’utilisationpour 1 000 requêtes standard | Abonnements | Crédits inclus par période de facturation |
|---|---|---|---|
| Paiement à l’usage | 0,50 $US | Pas de frais mensuels | Rechargez selon vos besoins |
| Micro | 0,40 $US | 49,00 $US / mois | 1 000 crédits (50,00 $US d’utilisation de l’API) inclus |
| Starter | 0,35 $US | 199,00 $US / mois | 4 000 crédits (200,00 $US d’utilisation de l’API) inclus |
| Pro | 0,30 $US | 499,00 $US / mois | 10 000 crédits (500,00 $US d’utilisation de l’API) inclus |
| Scale | 0,25 $US | 999,00 $US / mois | 20 000 crédits (1 000,00 $US d’utilisation de l’API) inclus |
| Business | 0,20 $US | 1 999,00 $US / mois | 40 000 crédits (2 000,00 $US d’utilisation de l’API) inclus |
Un seul forfait par compte. Des crédits partagés entre les trois produits. L’utilisation couverte par les crédits inclus n’est pas facturée à nouveau.
Tarifs actuels et limites des forfaits