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

Exemples

Récupérer des sous-titres horodatés

Enregistrez une piste de sous-titres YouTube existante avec son texte, ses horodatages et sa langue. Ajoutez un lien vidéo à chaque segment pour citer les passages dans votre application ou dans la réponse de votre agent.

Sur cette page

Avant de commencer

Utilisez une clé autorisant youtube_captions et un compte disposant de crédits. Choisissez Python 3.10+ avec requests, ou Bash avec cURL 7.76+ et jq. Sous Windows, utilisez Git Bash pour la version Bash.

1. Choisir la vidéo et la piste de sous-titres

Créez un dossier timestamped-captions et enregistrez-y request.json. Ouvrez un terminal dans ce dossier. Remplacez video_id par l’identifiant à 11 caractères de la vidéo, et non son URL complète.

Cet exemple demande les sous-titres automatiques en anglais. Avec auto=true, en essaie d’abord en-orig, puis en. Un code explicite se terminant par -orig ou une requête avec auto=false reste exact. L’API ne bascule jamais entre les sous-titres automatiques et ceux fournis par l’auteur.

timestamped-captions/request.json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}

2. Récupérer et enregistrer les sous-titres

Choisissez une version et enregistrez son script à côté de request.json. Il lit FLASHDATA_API_KEY ou vous demande la clé sans l’afficher. Les agents doivent charger cette variable d’environnement depuis leur gestionnaire de secrets.

Utilisez track-001 comme dossier de sortie. Un nouveau dossier déclenche une requête et enregistre sa consommation déclarée. Avant de créer captions.json, le script vérifie l’identifiant vidéo, la langue, l’origine des sous-titres et les horodatages des segments retournés.

Installer dans votre environnement Python
python -m pip install requests
timestamped-captions/captions.py
import argparse
import getpass
import json
import math
import os
import re
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved caption request")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if (not isinstance(request, dict) or request.get("source") != "youtube_captions"
            or not isinstance(request.get("video_id"), str)
            or not re.fullmatch(r"[A-Za-z0-9_-]{11}", request["video_id"])):
        raise SystemExit("Use youtube_captions and an 11-character video_id")
    options = request.get("params")
    if (not isinstance(options, dict) or not isinstance(options.get("language"), str)
            or not re.fullmatch(r"[A-Za-z0-9-]{1,35}", options["language"])
            or type(options.get("auto")) is not bool):
        raise SystemExit("Set one language code and auto: true or false explicitly")
    key = os.environ.get("FLASHDATA_API_KEY") or getpass.getpass("FlashData API key: ")
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")
try:
    data = json.loads((out / "result.json").read_bytes())
except ValueError:
    raise SystemExit("Invalid JSON; inspect the saved result.json")
request = json.loads((out / "request.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "youtube_captions" or data.get("status") != "done":
    raise SystemExit("Caption request did not finish successfully; inspect result.json")
tracks = data.get("results")
if not isinstance(tracks, list) or len(tracks) != 1 or not isinstance(tracks[0], dict):
    raise SystemExit("Expected one caption track; inspect result.json")
track = tracks[0]
language = request["params"]["language"]
allowed_languages = [language]
if request["params"]["auto"] and not language.endswith("-orig"):
    allowed_languages.append(language + "-orig")
if (track.get("videoId") != request["video_id"]
        or track.get("languageCode") not in allowed_languages
        or track.get("requestedLanguageCode", track.get("languageCode")) != language
        or track.get("isAutoGenerated") is not request["params"]["auto"]):
    raise SystemExit("Returned video, language or caption origin does not match the request")
if not isinstance(track.get("segments"), list):
    raise SystemExit("Expected a segments array; inspect result.json")
segments = []
for cue in track["segments"]:
    if not isinstance(cue, dict):
        raise SystemExit("Expected caption segment objects")
    start, end, text = cue.get("start"), cue.get("end"), cue.get("text")
    if (type(start) not in (int, float) or not math.isfinite(start) or start < 0
            or type(end) not in (int, float) or not math.isfinite(end) or end < start
            or not isinstance(text, str)):
        raise SystemExit("Invalid caption timing or text; inspect result.json")
    segments.append({**cue, "url": f"https://www.youtube.com/watch?v={track['videoId']}&t={math.floor(start)}s"})
captions = {**track, "segments": segments}
record = {"request": request, "requested_at": (out / "requested-at.txt").read_text().strip(),
          "usage": data.get("usage"), "segment_count": len(segments), "result_file": "result.json"}
for filename, value in (("captions.json", captions), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {len(segments)} segments to {out}/captions.json")
if not any(cue["text"].strip() for cue in segments):
    print("No caption text to cite. Keep the empty track and report the gap.")
Exécuter depuis timestamped-captions/
python captions.py track-001

3. Lire le texte horodaté

En cas de succès, le script affiche Saved N segments to track-001/captions.json. Ce fichier conserve la piste retournée et ajoute une URL à chaque segment. record.json contient la requête exacte, requested_at, usage et segment_count ; result.json conserve la réponse API d’origine.

Lire localement · aucun appel API
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.json

Exemple de sortie

Extrait illustratif de captions.json. Le texte et les horodatages retournés seront différents. languageName peut valoir null ; le script conserve cette valeur.

timestamped-captions/track-001/captions.json
{
  "videoId": "FUfGcZ092b0",
  "languageCode": "en",
  "languageName": null,
  "isAutoGenerated": true,
  "segments": [
    {
      "start": 12.5,
      "end": 16.2,
      "text": "This is an illustrative caption segment.",
      "url": "https://www.youtube.com/watch?v=FUfGcZ092b0&t=12s"
    }
  ]
}

Citer un passage de la vidéo

Affichez les trois premiers segments avec leurs liens source. start et end restent en secondes avec leur précision d’origine. Seul le début dans l’URL est arrondi à l’entier inférieur : 12,5 secondes devient &t=12s. L’ordre des segments et les chevauchements temporels sont conservés.

Enregistrez cite.py à côté de captions.py, puis exécutez-le depuis ce même dossier.

timestamped-captions/cite.py
import json
from pathlib import Path

captions = json.loads(Path("track-001/captions.json").read_text(encoding="utf-8"))
for cue in captions["segments"][:3]:
    print(f"[{cue['start']}–{cue['end']}s] {cue['text']}")
    print(cue["url"])
    print()
Afficher les citations des sous-titres enregistrés
python cite.py

Conserver le contexte des sous-titres

Utilisez le texte du segment pour étayer une citation ; fullText facilite la lecture, mais ne situe pas un passage. Lisez les segments voisins avant de citer, surtout pour les sous-titres automatiques. Conservez languageCode et isAutoGenerated pour que votre application ou votre agent identifie la piste source.

Réutiliser la piste enregistrée

Relancez la même commande pour reconstruire captions.json à partir de la réponse enregistrée, sans clé ni nouvelle requête. Modifier request.json à la racine du dossier ne change pas la requête conservée dans track-001.

Réutiliser localement
python captions.py track-001

Choisir une autre piste

Pour demander les sous-titres anglais fournis par l’auteur, remplacez request.json par cette version et utilisez track-002. Définissez language sur le code que vous souhaitez récupérer, par exemple en-orig ou zh-Hans. Le champ transcriptLanguages des métadonnées liste les codes possibles, sans indiquer si chacun possède une piste automatique ou fournie par l’auteur.

Le script attend une seule langue sous forme de chaîne. Les tableaux de langues produisent une réponse différente, avec tracks et des erreurs par langue ; consultez la référence API pour ce cas.

timestamped-captions/request.json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": false
  }
}
Nouvelle piste · nouvelle requête API
python captions.py track-002

Si les sous-titres sont absents ou inutilisables

ProblèmeSolution
La piste sélectionnée est indisponibleVérifiez la vidéo, la langue et la valeur de auto. Choisissez explicitement une piste disponible ; répéter la même requête ne crée pas de sous-titres.
segments: []Une piste existante peut ne contenir aucun texte. Le script enregistre cette piste vide et signale l’absence de contenu. N’en produisez pas une transcription ou un résumé.
Vidéo, langue ou origine des sous-titres incorrecteAucun fichier captions.json n’est écrit. Comparez la requête enregistrée à result.json avant d’utiliser le texte.
Horodatages invalides ou segments absentsInspectez result.json. Le script s’arrête au lieu d’inventer des horodatages ou d’omettre silencieusement un segment incorrect.
401 / 403 / 402Vérifiez respectivement la clé, l’autorisation youtube_captions et le solde avant une nouvelle tentative.
429Lisez Retry-After dans response-headers.txt et attendez. Le script ne réessaie pas automatiquement.
Délai dépassé, erreur 5xx, JSON invalide ou dossier incompletConservez la tentative et consultez History avant de soumettre à nouveau la requête. Réutiliser son dossier n’envoie jamais de nouvelle requête.

Enregistrez inspect_captions.py à côté de captions.py, puis exécutez-le.

timestamped-captions/inspect_captions.py
from pathlib import Path

for name in ("http-status.txt", "response-headers.txt", "result.json"):
    path = Path("track-001") / name
    print(f"--- {name} ---")
    print(path.read_text(encoding="utf-8", errors="replace") if path.exists() else "Not saved")
Inspecter localement
python inspect_captions.py