Parcourir la documentation
Exemples
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.
{
"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.
python -m pip install requestsimport 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.")
python captions.py track-001curl --version
jq --version#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash captions.sh OUTPUT_FOLDER}"
if [[ ! -e "$out" ]]; then
jq -e '.source == "youtube_captions" and
(.video_id | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$") else false end) and
(.params.language | if type == "string" then length > 0 and length <= 35 and
(test("[^A-Za-z0-9-]") | not) else false end) and
(.params.auto | type == "boolean")' request.json > /dev/null
if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
fi
: "${FLASHDATA_API_KEY:?An API key is required}"
mkdir -- "$out"
cp request.json "$out/request.json"
date -u +'%Y-%m-%dT%H:%M:%SZ' > "$out/requested-at.txt"
curl --fail-with-body --silent --show-error --max-time 120 \
--request POST 'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' --header 'Accept: application/json' \
--data-binary "@$out/request.json" \
--dump-header "$out/response-headers.txt" --output "$out/result.json" \
--write-out '%{http_code}' > "$out/http-status.txt" || {
printf 'Request failed. Keep %s and inspect its saved files before retrying.\n' "$out" >&2
exit 1
}
else
printf 'Reading saved response from %s; no API call.\n' "$out"
fi
if [[ ! -f "$out/http-status.txt" ]] || [[ "$(cat "$out/http-status.txt")" != 200 ]]; then
printf 'Incomplete or failed attempt. Inspect the saved files and History before retrying.\n' >&2
exit 1
fi
captions=$(jq -e --slurpfile request "$out/request.json" '
if .source != "youtube_captions" or .status != "done"
then error("Expected a successful youtube_captions response") else . end
| .results
| if type != "array" then error("Expected a results array")
elif length != 1 then error("Expected exactly one track") else .[0] end
| $request[0].params.language as $language
| if type != "object" then error("Expected a caption object")
elif .videoId != $request[0].video_id or (.requestedLanguageCode // .languageCode) != $language
or (.languageCode != $language and ($request[0].params.auto != true
or ($language | endswith("-orig")) or .languageCode != ($language + "-orig")))
or .isAutoGenerated != $request[0].params.auto
then error("Returned video, language or caption origin does not match the request") else . end
| if (.segments | type) != "array" then error("Expected a segments array") else . end
| .videoId as $id
| .segments |= map(
if type != "object" then error("Expected caption segment objects") else . end
| if (.start | type) != "number" or (.end | type) != "number" or (.text | type) != "string"
then error("Invalid caption timing or text")
elif (.start | isfinite | not) or (.end | isfinite | not) or .start < 0 or .end < .start
then error("Invalid caption timing")
else . + {url: ("https://www.youtube.com/watch?v=" + $id + "&t=" + (.start | floor | tostring) + "s")} end
)' "$out/result.json")
printf '%s\n' "$captions" > "$out/captions.json"
jq --slurpfile request "$out/request.json" --slurpfile captions "$out/captions.json" \
--arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
'{request: $request[0], requested_at: $requested_at, usage,
segment_count: ($captions[0].segments | length), result_file: "result.json"}' \
"$out/result.json" > "$out/record.json"
printf 'Saved %s segments to %s/captions.json\n' "$(jq '.segments | length' "$out/captions.json")" "$out"
if ! jq -e 'any(.segments[]; .text | test("\\S"))' "$out/captions.json" > /dev/null; then
printf 'No caption text to cite. Keep the empty track and report the gap.\n'
fi
bash captions.sh track-0013. 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.
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.jsoncat track-001/captions.json
cat track-001/record.jsonExemple 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.
{
"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.
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()python cite.pyjq -r '.segments[:3][] |
"[\(.start)–\(.end)s] \(.text)\n\(.url)\n"' track-001/captions.jsonConserver 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.
python captions.py track-001bash captions.sh track-001Choisir 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.
{
"source": "youtube_captions",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": false
}
}python captions.py track-002bash captions.sh track-002Si les sous-titres sont absents ou inutilisables
| Problème | Solution |
|---|---|
| La piste sélectionnée est indisponible | Vé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 incorrecte | Aucun fichier captions.json n’est écrit. Comparez la requête enregistrée à result.json avant d’utiliser le texte. |
| Horodatages invalides ou segments absents | Inspectez result.json. Le script s’arrête au lieu d’inventer des horodatages ou d’omettre silencieusement un segment incorrect. |
| 401 / 403 / 402 | Vérifiez respectivement la clé, l’autorisation youtube_captions et le solde avant une nouvelle tentative. |
| 429 | Lisez 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 incomplet | Conservez 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.
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")python inspect_captions.pyfor name in http-status.txt response-headers.txt result.json; do
printf '\n--- %s ---\n' "$name"
if [[ -f "track-001/$name" ]]; then cat "track-001/$name"; else printf 'Not saved\n'; fi
done