Parcourir la documentation
Exemples
À partir d’un identifiant YouTube, enregistrez le titre, la chaîne, la durée et les compteurs disponibles. Conservez aussi la réponse d’origine et la consommation.
Sur cette page
Avant de commencer
Utilisez une clé autorisant youtube_metadata 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 une vidéo
Créez un dossier video-metadata et enregistrez-y request.json. Ouvrez un terminal dans ce dossier. Remplacez video_id par l’identifiant à 11 caractères tiré d’une URL de lecture ou d’un résultat YouTube Search ; ne fournissez pas l’URL complète.
Définissez explicitement les deux options facultatives : cette première requête exclut les formats multimédias et les chapitres. Elle récupère les métadonnées sans télécharger la vidéo ni ses sous-titres.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": false
}
}2. Récupérer et enregistrer les métadonnées
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 snapshot-001 comme dossier de sortie. Un nouveau dossier déclenche une requête de métadonnées et enregistre sa consommation déclarée. Avant d’écrire video.json, le script vérifie que la réponse a réussi et contient exactement une vidéo portant l’identifiant demandé.
python -m pip install requestsimport argparse
import getpass
import json
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 snapshot")
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_metadata"
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_metadata and an 11-character video_id, not a URL")
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_metadata" or data.get("status") != "done":
raise SystemExit("Metadata request did not finish successfully; inspect result.json")
videos = data.get("results")
if (not isinstance(videos, list) or len(videos) != 1 or not isinstance(videos[0], dict)
or videos[0].get("videoId") != request["video_id"]):
raise SystemExit("Expected one metadata object matching the requested video_id")
record = {
"request": request,
"requested_at": (out / "requested-at.txt").read_text().strip(),
"usage": data.get("usage"), "result_file": "result.json",
}
for filename, value in (("video.json", videos[0]), ("record.json", record)):
(out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {videos[0]['videoId']} to {out}/video.json")
python metadata.py snapshot-001curl --version
jq --version#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash metadata.sh OUTPUT_FOLDER}"
if [[ ! -e "$out" ]]; then
jq -e '.source == "youtube_metadata" and
(.video_id | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$")
else false end)' 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
video=$(jq -e --slurpfile request "$out/request.json" '
if .source != "youtube_metadata" or .status != "done"
then error("Expected a successful youtube_metadata response") else . end
| .results
| if type != "array" then error("Expected a metadata array")
elif length != 1 then error("Expected exactly one video") else .[0] end
| if type != "object" then error("Expected a metadata object")
elif .videoId != $request[0].video_id then error("Returned videoId does not match the request")
else . end' "$out/result.json")
printf '%s\n' "$video" > "$out/video.json"
jq --slurpfile request "$out/request.json" \
--arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
'{request: $request[0], requested_at: $requested_at, usage, result_file: "result.json"}' \
"$out/result.json" > "$out/record.json"
printf 'Saved %s to %s/video.json\n' "$(jq -r .videoId "$out/video.json")" "$out"
bash metadata.sh snapshot-0013. Lire les informations de la vidéo
En cas de succès, le script affiche Saved <video ID> to snapshot-001/video.json. Ce fichier contient l’objet de métadonnées complet ; record.json conserve la requête exacte, requested_at et usage. Lire ces fichiers ne déclenche aucun appel API.
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.jsoncat snapshot-001/video.json
cat snapshot-001/record.jsonExemple de sortie
Extrait illustratif de video.json. Les valeurs retournées varient. Le script conserve tous les champs disponibles, y compris les valeurs null, et garde la réponse complète dans result.json.
{
"videoId": "FUfGcZ092b0",
"title": "Example research video",
"channel": "Example channel",
"duration": 120,
"viewCount": null,
"transcriptLanguages": [
"en"
]
}Comprendre les champs
| Champ | Utilisation |
|---|---|
| videoId | Clé stable de l’enregistrement. Le titre et le nom affiché de la chaîne peuvent changer. |
| duration | Durée de la vidéo en secondes. Conservez les valeurs manquantes ou null comme inconnues. |
| viewCount / likeCount / commentCount | Compteurs disponibles dans cet instantané. Une valeur null ou absente est inconnue ; zéro est une valeur effectivement renvoyée. |
| transcriptLanguages | Codes de langue possibles pour une requête de sous-titres distincte. Cette liste n’indique pas si la piste est automatique ou fournie par l’auteur. |
Réutiliser l’instantané ou en demander un autre
Relancez la même commande pour reconstruire video.json et record.json à partir de la réponse enregistrée. Aucune clé ni requête réseau n’est nécessaire. Modifier request.json à la racine du dossier ne change pas l’entrée conservée dans snapshot-001.
python metadata.py snapshot-001bash metadata.sh snapshot-001Inclure les chapitres disponibles
Pour inclure les repères de chapitre, remplacez request.json par cette version et utilisez un nouveau dossier de sortie. include_chapters: true renvoie les chapitres disponibles ; il ne les crée pas. include_chapters et include_formats valent tous deux true lorsqu’ils sont omis.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": true
}
}python metadata.py snapshot-002bash metadata.sh snapshot-002Si les métadonnées sont indisponibles
| Problème | Solution |
|---|---|
| video_id invalide | Utilisez uniquement l’identifiant à 11 caractères. La validation bloque une entrée invalide avant l’envoi de la requête. |
| Vidéo privée, supprimée ou soumise à des restrictions | Conservez l’échec associé à cet identifiant. Examinez l’erreur de la source et choisissez une vidéo accessible au lieu de soumettre plusieurs fois le même élément. |
| Résultat vide ou videoId différent | Le script s’arrête sans écrire video.json. Inspectez la requête et la réponse enregistrées avant d’utiliser cet enregistrement. |
| Compteurs, chapitres ou langues absents | Un enregistrement correspondant à la vidéo peut tout de même constituer un résultat réussi. Conservez les champs indisponibles comme inconnus ; ne leur attribuez pas de valeurs inventées. |
| 401 / 403 / 402 | Vérifiez respectivement la clé, l’autorisation youtube_metadata et le solde avant une nouvelle tentative. |
| 429 | Lisez Retry-After dans response-headers.txt et attendez. Le script ne réessaie jamais 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 aucune nouvelle requête. |
Enregistrez inspect_metadata.py à côté de metadata.py, puis exécutez-le.
from pathlib import Path
for name in ("http-status.txt", "response-headers.txt", "result.json"):
path = Path("snapshot-001") / name
print(f"--- {name} ---")
print(path.read_text(encoding="utf-8", errors="replace") if path.exists() else "Not saved")python inspect_metadata.pyfor name in http-status.txt response-headers.txt result.json; do
printf '\n--- %s ---\n' "$name"
if [[ -f "snapshot-001/$name" ]]; then cat "snapshot-001/$name"; else printf 'Not saved\n'; fi
doneUtiliser la vidéo dans votre workflow
Utilisez videoId pour relier cet enregistrement à vos résultats de recherche ou à votre jeu de données. Pour le contenu parlé, récupérez ensuite une piste de sous-titres précise. Pour plusieurs identifiants, suivez le guide d’enrichissement. Ces requêtes sont distinctes et ont leurs propres autorisations et coûts.