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

Exemples

Récupérer les métadonnées d’une vidéo

À 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.

video-metadata/request.json
{
  "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é.

Installer dans votre environnement Python
python -m pip install requests
video-metadata/metadata.py
import 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")
Exécuter depuis video-metadata/
python metadata.py snapshot-001

3. 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.

Lire localement
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.json

Exemple 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.

video-metadata/snapshot-001/video.json
{
  "videoId": "FUfGcZ092b0",
  "title": "Example research video",
  "channel": "Example channel",
  "duration": 120,
  "viewCount": null,
  "transcriptLanguages": [
    "en"
  ]
}

Comprendre les champs

ChampUtilisation
videoIdClé stable de l’enregistrement. Le titre et le nom affiché de la chaîne peuvent changer.
durationDurée de la vidéo en secondes. Conservez les valeurs manquantes ou null comme inconnues.
viewCount / likeCount / commentCountCompteurs disponibles dans cet instantané. Une valeur null ou absente est inconnue ; zéro est une valeur effectivement renvoyée.
transcriptLanguagesCodes 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.

Réutiliser les données enregistrées
python metadata.py snapshot-001

Inclure 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.

video-metadata/request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": true
  }
}
Demander un autre instantané
python metadata.py snapshot-002

Si les métadonnées sont indisponibles

ProblèmeSolution
video_id invalideUtilisez 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 restrictionsConservez 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érentLe 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 absentsUn 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 / 402Vérifiez respectivement la clé, l’autorisation youtube_metadata et le solde avant une nouvelle tentative.
429Lisez 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 incompletConservez 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.

video-metadata/inspect_metadata.py
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")
Inspecter localement
python inspect_metadata.py

Utiliser 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.