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

Guides

Bonnes pratiques : données YouTube

Trouvez des vidéos pertinentes, sélectionnez les pistes de sous-titres et traitez les nouvelles vidéos d’une chaîne sans répéter les tâches.

Sur cette page

Partir des informations déjà disponibles

Chaque source répond à une question différente. Si vous connaissez l’identifiant vidéo ou le handle de la chaîne, passez directement aux données correspondantes. Enrichissez uniquement les vidéos nécessaires à votre tâche.

Votre tâcheSourceDécision
Trouver des vidéos sur un sujetyoutube_searchCommencez par cinq candidats, puis choisissez selon leur pertinence.
Examiner une vidéo connueyoutube_metadataObtenir le titre, la chaîne, la durée et les langues des sous-titres.
Résumer ou citer les propos tenusyoutube_transcript / youtube_captionsChoisir une langue et une piste automatique ou manuelle.
Vérifier les vidéos récentes d’une chaîneyoutube_channelComparer les identifiants reçus à ceux des vidéos déjà traitées.

Exécuter les exemples de requêtes

Enregistrez chaque corps JSON sous le nom de fichier indiqué. Python utilise le script query.py ci-dessous ; cURL peut soumettre le même fichier. Utilisez une clé disposant des permissions de source nécessaires et des crédits disponibles. Chaque soumission représente une requête, quel que soit le nombre de vidéos renvoyées.

Python 3.10+. Installez requests une fois, enregistrez query.py ci-dessous, puis utilisez la commande à côté de chaque requête. Les sorties existantes sont réutilisées ; des paramètres différents nécessitent un nouveau nom de fichier de sortie.

Installer
python -m pip install requests

Définir votre clé API

Réutilisez FLASHDATA_API_KEY depuis votre terminal ou votre stockage de secrets. Sinon, saisissez la clé dans l’une des invites masquées ci-dessous. Gardez-la dans l’environnement du processus qui exécute ces exemples.

Définir la clé
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY

Enregistrer query.py pour les exemples Python

Créez query.py dans un nouveau dossier de travail et copiez-y tout le code ci-dessous. Enregistrez les fichiers JSON de requête et les autres scripts Python dans ce dossier, puis exécutez toutes les commandes depuis celui-ci.

query.py
# query.py — submit a saved request once, then reuse its response.
import json
import os
import sys
from pathlib import Path
import requests

if len(sys.argv) != 3:
    raise SystemExit("Usage: python query.py REQUEST.json RESULT.json")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2])
marker = output.with_name(output.name + ".request.json")
receipt = output.with_name(output.name + ".http.json")
if marker.exists():
    if json.loads(marker.read_text()) != payload:
        raise SystemExit("Changed request: choose a new output filename.")
    if not output.exists() or not receipt.exists():
        raise SystemExit("Outcome unknown: check History before resubmitting.")
    saved = json.loads(receipt.read_text())
    if saved["status"] != 200 or json.loads(output.read_text(encoding="utf-8")).get("status") != "done":
        raise SystemExit(f"Saved request failed or incomplete; Retry-After: {saved['retry_after']}. Inspect {output}.")
    print(f"Read the saved {output}; no new query submitted.")
    raise SystemExit(0)
if output.exists():
    raise SystemExit("Output already exists. Read it or choose a new filename.")
key = os.environ["FLASHDATA_API_KEY"]
with marker.open("x", encoding="utf-8") as file:
    json.dump(payload, file)
response = requests.post("https://data.flashdata.dev/v1/queries/realtime",
                         headers={"X-API-Key": key}, json=payload,
                         timeout=70, allow_redirects=False)
output.write_text(response.text, encoding="utf-8")
receipt.write_text(json.dumps({"status": response.status_code,
                               "retry_after": response.headers.get("Retry-After")}), encoding="utf-8")
if response.status_code != 200:
    raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
if response.json().get("status") != "done":
    raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"saved": str(output), "usage": response.json().get("usage")}, indent=2))

Trouver des candidats avant de récupérer les détails

Le filtre video exclut les autres types de résultats ; subtitles limite la recherche aux vidéos sous-titrées. Il ne sélectionne pas de langue et ne garantit pas la piste recherchée. Enregistrez le corps de requête dans discover-request.json.

discover-request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
Soumettre une fois avec query.py
python query.py discover-request.json search.json

Choisir selon la pertinence, pas le premier identifiant

Enregistrez candidates.py à côté de query.py et search.json, puis lancez-le depuis ce dossier. Il conserve l’ordre des résultats et supprime les identifiants vidéo en double. Examinez les titres, les chaînes et la durée, puis copiez l’identifiant choisi dans la requête suivante. Une liste vide correspond à une recherche terminée sans candidat.

candidates.py
# candidates.py — read a saved response; no API calls.
import json
import re
from pathlib import Path

data = json.loads(Path("search.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
    raise SystemExit("Search did not complete; inspect search.json.")
candidates, seen = [], set()
for item in (data.get("results") or [{}])[0].get("results", []):
    video_id = item.get("videoId", "")
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id) or video_id in seen:
        continue
    seen.add(video_id)
    candidates.append({"videoId": video_id, "title": item.get("title"),
                       "channel": item.get("channel"), "duration": item.get("duration"),
                       "url": "https://www.youtube.com/watch?v=" + video_id})
Path("candidates.json").write_text(json.dumps(candidates, indent=2), encoding="utf-8")
print(json.dumps(candidates, indent=2))
Lire les résultats de recherche enregistrés
python candidates.py

Élargir uniquement si la sélection est insuffisante

La recherche standard accepte max_results jusqu’à 20. Pour une collecte plus large, utilisez youtube_search_extended, qui accepte jusqu’à 700 résultats avec une tarification distincte. Cet exemple en demande 50 ; vérifiez l’utilité des premiers résultats avant de tous les enrichir.

extended-request.json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
Exécuter une fois
python query.py extended-request.json extended.json

Récupérer uniquement les métadonnées nécessaires

Remplacez le video_id d’exemple par l’identifiant choisi. Laissez les formats et les chapitres désactivés pour une simple fiche vidéo ou une vérification des langues de sous-titres. Activez include_chapters pour obtenir le plan de la vidéo, ou include_formats pour choisir un format de média.

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Soumettre une fois avec query.py
python query.py metadata-request.json metadata.json

Examiner les langues disponibles

Lisez results[0].transcriptLanguages avant de choisir les sous-titres. Les formats, les chapitres et les langues sont des champs de l’objet vidéo reçu ; la consommation figure dans l’enveloppe de la réponse.

ParamètreUtilité
languageUn code issu de transcriptLanguages, par exemple en ou zh-Hans. Cette liste ne distingue pas les pistes manuelles des pistes automatiques.
auto: trueUne piste existante générée automatiquement.
auto: falseUne piste existante fournie manuellement. Il n’y a aucun basculement automatique entre les deux types de pistes.
Lire metadata.json · aucune requête
python -m json.tool metadata.json

Choisir explicitement la langue et la piste

Utilisez le même video_id que pour la requête de métadonnées et adaptez language et auto à la piste choisie. youtube_transcript utilise auto: true par défaut ; youtube_captions utilise auto: false. Les deux récupèrent des sous-titres existants, sans transcrire l’audio.

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Soumettre une fois avec query.py
python query.py captions-request.json captions.json

Conserver l’horodatage avec chaque extrait

Enregistrez cite-segments.py à côté de captions.json et lancez-le depuis ce dossier. Utilisez results[0].segments pour les citations : start et end sont exprimés en secondes. Conservez languageCode et isAutoGenerated avec le texte. fullText facilite la lecture, mais ne remplace pas les horodatages des segments. Si la piste choisie manque, signalez cette lacune avant de décider si une autre requête est utile.

cite-segments.py
import json
from pathlib import Path

response = json.loads(Path("captions.json").read_text(encoding="utf-8"))
if response.get("status") != "done":
    raise SystemExit("Inspect captions.json before continuing.")
track = (response.get("results") or [{}])[0]
if not track.get("segments"):
    raise SystemExit("No caption evidence was returned.")
for segment in track["segments"][:3]:
    url = f"https://www.youtube.com/watch?v={track['videoId']}&t={int(segment['start'])}s"
    print(segment["text"], url)
Lire les sous-titres enregistrés · aucun appel API
python cite-segments.py

Traiter uniquement les nouvelles vidéos d’une chaîne connue

Utilisez le handle d’une chaîne et une valeur video_limit bornée (1–100). results[0].videos contient la liste des vidéos récentes reçues ; videoCount est une métadonnée de la chaîne, pas le nombre d’éléments renvoyés. Choisissez une limite et une fréquence de vérification adaptées aux publications à suivre.

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Soumettre une fois avec query.py
python query.py channel-request.json channel.json

Conserver une file d’attente et un point de reprise

Enregistrez channel-queue.py à côté de query.py et channel.json, puis lancez-le depuis ce dossier. Exécutez-le sans argument pour créer new-ids.json, puis traitez ces identifiants et enregistrez leurs sources. Lancez --commit uniquement lorsque tous les identifiants en attente ont été traités avec succès ; un échec laisse le point de reprise inchangé. Utilisez un dossier par chaîne et un seul processus de traitement pour cet exemple.

channel-queue.py
# channel-queue.py — plan first; commit only after every queued video is processed.
import json
import re
import sys
from pathlib import Path

checkpoint = Path("processed-ids.json")
processed = set(json.loads(checkpoint.read_text()) if checkpoint.exists() else [])
queue = Path("new-ids.json")
if sys.argv[1:] == ["--commit"]:
    processed.update(json.loads(queue.read_text()))
    temporary = checkpoint.with_suffix(".tmp")
    temporary.write_text(json.dumps(sorted(processed)), encoding="utf-8")
    temporary.replace(checkpoint)
    queue.unlink()
    print("Checkpoint saved.")
elif sys.argv[1:]:
    raise SystemExit("Usage: python channel-queue.py [--commit]")
else:
    data = json.loads(Path("channel.json").read_text(encoding="utf-8"))
    if data.get("status") != "done":
        raise SystemExit("Channel query did not complete.")
    ids = dict.fromkeys(video.get("videoId", "") for video in
                        (data.get("results") or [{}])[0].get("videos", []))
    new = [value for value in ids if re.fullmatch(r"[A-Za-z0-9_-]{11}", value)
           and value not in processed]
    if queue.exists() and json.loads(queue.read_text()) != new:
        raise SystemExit("Finish the existing queue before replacing it.")
    queue.write_text(json.dumps(new, indent=2), encoding="utf-8")
    print(json.dumps(new, indent=2))
Préparer → traiter → valider
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

Lancer volontairement une nouvelle vérification de chaîne

Le script de requête réutilise une réponse enregistrée. Pour la prochaine vérification planifiée, choisissez un nouveau nom de fichier de résultat, examinez-le, puis copiez cette réponse terminée dans channel.json pour l’étape de mise en file. Conservez processed-ids.json entre les exécutions. Cette liste récente n’est ni un export complet de la chaîne ni un flux d’événements.

Prochaine vérification · choisir un nouveau nom de fichier
python query.py channel-request.json channel-next.json
Après avoir confirmé status: done
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"

Utiliser les suggestions pour améliorer la requête

Les suggestions renvoient des expressions dans results[0], pas des objets vidéo. Choisissez une expression utile, puis effectuez une requête youtube_search distincte. Définissez la langue et la région du public étudié.

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Soumettre une fois avec query.py
python query.py suggestions-request.json suggestions.json

Conserver les indications de licence sans les assimiler à une autorisation

youtube_trainability renvoie une indication de licence pour une vidéo. permitted: ["all"] correspond à Creative Commons ; ["none"] couvre aussi l’absence de métadonnées de licence. Conservez l’identifiant vidéo, la réponse source et la date de récupération. Cette indication n’accorde aucun droit de téléchargement, de réutilisation ou d’entraînement.

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Soumettre une fois avec query.py
python query.py license-request.json license.json

Limiter le travail des applications et des agents

RègleMise en œuvre
Sélectionner avant d’enrichirPour une tâche thématique : une recherche, les métadonnées d’une vidéo sélectionnée et une piste de sous-titres choisie. Faites respecter le nombre d’appels prévu dans votre application et calculez séparément le prix de chaque source.
Réutiliser selon les paramètres exactsMétadonnées : identifiant vidéo + options. Sous-titres : identifiant vidéo + langue + piste. Les instantanés de chaîne nécessitent aussi une date de récupération ou un identifiant d’exécution.
S’arrêter si les sources manquentNe relancez pas une recherche vide et ne changez pas de piste de sous-titres sans le signaler. Indiquez ce qui manque pour que l’utilisateur ou le workflow choisisse l’action suivante.
Conserver la consommation et les échecsEnregistrez la consommation avec les réponses réussies. En cas de 429, respectez Retry-After ; après une soumission incertaine, consultez History avant toute nouvelle requête payante.