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

Référence canonique : https://flashdata.dev/fr/docs/guides/youtube-data-guide
Vérifié le 2026-11-04 par FlashData

<a id="choose"></a>

## 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âche | Source | Décision |
| --- | --- | --- |
| Trouver des vidéos sur un sujet | youtube_search | Commencez par cinq candidats, puis choisissez selon leur pertinence. |
| Examiner une vidéo connue | youtube_metadata | Obtenir le titre, la chaîne, la durée et les langues des sous-titres. |
| Résumer ou citer les propos tenus | youtube_transcript / youtube_captions | Choisir une langue et une piste automatique ou manuelle. |
| Vérifier les vidéos récentes d’une chaîne | youtube_channel | Comparer les identifiants reçus à ceux des vidéos déjà traitées. |

- [Trouver des vidéos](https://flashdata.dev/fr/docs/guides/youtube-data-guide/reference.md#discover)
- [Travailler avec une vidéo connue](https://flashdata.dev/fr/docs/guides/youtube-data-guide/reference.md#metadata)
- [Suivre une chaîne](https://flashdata.dev/fr/docs/guides/youtube-data-guide/reference.md#channel)

<a id="setup"></a>

## 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

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

```bash
python -m pip install requests
```


### cURL

Bash. Remplacez REQUEST.json et RESULT.json par les noms de fichiers de l’exemple choisi. Vérifiez le résultat avant de répéter une requête ; cette commande enregistre le corps HTTP même en cas d’erreur.

#### Soumettre une requête JSON enregistrée

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e RESULT.json || { echo 'Read RESULT.json first'; exit 1; }
curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @REQUEST.json --output RESULT.json
)
```



<a id="authenticate"></a>

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

#### Bash

##### Définir la clé

```bash
# 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
```


#### PowerShell 7

##### Définir la clé

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [Clés API](https://flashdata.dev/app/api-keys)
- [Essai et rattachement d’un agent](https://flashdata.dev/fr/docs/guides/agent-onboarding/reference.md)

<a id="runner"></a>

### 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

```python
# 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))
```


<a id="discover"></a>

## 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

```json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
```

### Soumettre une fois avec query.py

```bash
python query.py discover-request.json search.json
```


<a id="candidates"></a>

### 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

```python
# 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

```bash
python candidates.py
```


<a id="extended"></a>

### É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

```json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
```

#### Exécuter une fois

```bash
python query.py extended-request.json extended.json
```

- [Soumettre une recherche longue en mode asynchrone](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#async)
- [Enrichir les identifiants sélectionnés](https://flashdata.dev/fr/docs/guides/enrich-youtube-videos/reference.md)

<a id="metadata"></a>

## 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

```json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
```

### Soumettre une fois avec query.py

```bash
python query.py metadata-request.json metadata.json
```

- [Champs de réponse des métadonnées](https://flashdata.dev/fr/docs/sources/youtube_metadata/reference.md#response)
- [Workflow de livraison de médias](https://flashdata.dev/fr/docs/guides/media-delivery-pipeline/reference.md)

<a id="tracks"></a>

### 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ètre | Utilité |
| --- | --- |
| language | Un code issu de transcriptLanguages, par exemple en ou zh-Hans. Cette liste ne distingue pas les pistes manuelles des pistes automatiques. |
| auto: true | Une piste existante générée automatiquement. |
| auto: false | Une piste existante fournie manuellement. Il n’y a aucun basculement automatique entre les deux types de pistes. |

#### Lire metadata.json · aucune requête

```bash
python -m json.tool metadata.json
```


<a id="captions"></a>

## 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

```json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
```

### Soumettre une fois avec query.py

```bash
python query.py captions-request.json captions.json
```

- [Paramètres des sous-titres](https://flashdata.dev/fr/docs/sources/youtube_transcript/reference.md#parameters)
- [Créer un résumé complet](https://flashdata.dev/fr/docs/guides/youtube-summary/reference.md)

<a id="citations"></a>

### 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

```python
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

```bash
python cite-segments.py
```


<a id="channel"></a>

## 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

```json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
```

### Soumettre une fois avec query.py

```bash
python query.py channel-request.json channel.json
```


<a id="channel-diff"></a>

### 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

```python
# 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

```bash
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit
```

- [Planifier et réutiliser les identifiants](https://flashdata.dev/fr/docs/guides/recurring-tasks/reference.md)
- [Enrichir une liste de vidéos](https://flashdata.dev/fr/docs/guides/enrich-youtube-videos/reference.md)

<a id="channel-checkpoint"></a>

### 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

```bash
python query.py channel-request.json channel-next.json
```

#### Après avoir confirmé status: done

```bash
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"
```


<a id="suggestions"></a>

## 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

```json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
```

### Soumettre une fois avec query.py

```bash
python query.py suggestions-request.json suggestions.json
```


<a id="license"></a>

## 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

```json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
```

### Soumettre une fois avec query.py

```bash
python query.py license-request.json license.json
```


<a id="operations"></a>

## Limiter le travail des applications et des agents

| Règle | Mise en œuvre |
| --- | --- |
| Sélectionner avant d’enrichir | Pour 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 exacts | Mé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 manquent | Ne 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 échecs | Enregistrez 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. |

- [Temps réel et asynchrone](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md)
- [Batch et bulk](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md)
- [Erreurs et nouvelles tentatives](https://flashdata.dev/fr/docs/errors/reference.md#retries)
- [Tarifs et solde actuels](https://flashdata.dev/fr/docs/guides/credits-and-billing/reference.md)
