Comment obtenir une clé API YouTube (YouTube Data API v3) et effectuer votre première requête

Une clé API YouTube est l'identifiant qui permet à votre code de lire les données publiques de YouTube : détails de vidéos, statistiques de chaînes, résultats de recherche, contenu de listes de lecture. La documentation de Google le dit clairement : « Une requête qui ne fournit pas de jeton OAuth 2.0 doit envoyer une clé API. La clé identifie votre projet et fournit l'accès à l'API, le quota et les rapports. » Pas de clé, pas de données.

Ce guide vous mènera d'un projet Google Cloud vide à une requête fonctionnelle en une quinzaine de minutes. Vous activerez l'API YouTube Data v3, créerez une clé, la sécuriserez, appellerez l'API depuis curl et Python, puis stockerez la clé dans Apidog et enregistrerez l'appel comme un test reproductible. Si vous voulez d'abord avoir une vue d'ensemble, notre aperçu de l'API YouTube Data couvre ce que l'API expose ; cet article est la partie pratique.

bouton

Ce dont vous avez besoin avant de commencer

Un compte Google. C'est suffisant pour ouvrir la Console Cloud et créer un projet.
curl (fourni avec macOS et la plupart des distributions Linux) et Python 3 avec le package requests pour les exemples de code.
Apidog si vous souhaitez que la clé soit stockée comme secret et que la requête soit enregistrée comme test. Le plan gratuit couvre tout ce qui est décrit ici.

Étape 1 : créer un projet Google Cloud

Ouvrez la Console Google Cloud et connectez-vous. Utilisez le sélecteur de projets en haut de la page pour créer un nouveau projet, par exemple youtube-integration. Chaque clé API, compartiment de quota et rapport d'utilisation que vous verrez plus tard est rattaché à ce projet, alors gardez un projet par application au lieu de partager une clé entre des outils non liés. Si l'application a déjà un projet, utilisez celui-ci.

Étape 2 : activer l'API YouTube Data v3

Les API sont désactivées par défaut dans un nouveau projet. Dans la console, accédez à API & Services, ouvrez la Bibliothèque d'API, recherchez « YouTube Data API v3 » et activez-la. Le guide de démarrage de Google décrit la même vérification dans l'autre sens : visitez la page des API activées et activez l'API si elle n'est pas listée.

Sautez cette étape et votre première requête échouera avec une erreur 403 indiquant que l'API n'a pas été utilisée dans le projet ou est désactivée. C'est la raison la plus courante pour laquelle une clé flambant neuve « ne fonctionne pas ».

Étape 3 : créer la clé API

Accédez à API & Services, puis à Identifiants. Cliquez sur Créer des identifiants et choisissez Clé API. La console génère immédiatement la clé et l'affiche dans une boîte de dialogue ; copiez-la en lieu sûr.

Traitez la clé comme un mot de passe. Ne la collez pas dans un dépôt Git, un fil Slack ou un bundle JavaScript côté client. Si elle s'est déjà glissée dans un commit, notre guide sur la recherche et la correction des clés API exposées couvre le nettoyage.

Étape 4 : restreindre la clé

La propre documentation de Google indique : « Les clés API non restreintes sont non sécurisées. » Juste après la création, cliquez sur Restreindre la clé. Vous disposez de deux contrôles indépendants, documentés dans le guide des clés API Cloud :

Restrictions d'application décident qui peut présenter la clé. Choisissez-en une : sites web (référents HTTP, avec un support limité des jokers), adresses IP (IPv4, IPv6 ou plages CIDR), applications Android (nom de package plus empreinte de certificat SHA-1) ou applications iOS (ID de bundle). Un service backend doit utiliser des adresses IP. Un widget uniquement pour navigateur doit utiliser des référents.
Restrictions d'API décident quelles API la clé peut appeler. Choisissez « Restreindre la clé » et sélectionnez uniquement l'API YouTube Data v3. Si la clé fuit, l'attaquant n'obtient que le quota YouTube et rien d'autre.

Enregistrez et laissez le changement prendre effet quelques minutes avant de tester. Deux autres habitudes du même guide : faites pivoter les clés périodiquement pour limiter les dommages d'une clé compromise, et supprimez les anciennes clés une fois que chaque appelant est passé au remplacement. Une particularité pour l'étape suivante : si vous restreignez par IP à votre serveur, curl depuis votre ordinateur portable est bloqué, alors testez depuis l'hôte autorisé ou créez une clé de développement séparée.

Étape 5 : effectuez votre première requête avec curl et Python

Chaque point d'accès dépend de https://www.googleapis.com/youtube/v3/. Transmettez la clé comme paramètre de requête key, comme le font les exemples de Google, ou dans un en-tête x-goog-api-key, ce qui la maintient hors des URL et des journaux d'accès. Les deux fonctionnent sur l'API en direct.

Commencez par videos.list, l'appel utile le moins cher : il renvoie les détails pour un ou plusieurs ID de vidéo et coûte 1 unité de quota. L'ID ci-dessous est celui que Google utilise dans sa documentation.

export YOUTUBE_API_KEY="AIza...your-key..."

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=7lCDEYXw3mM" \
  -H "x-goog-api-key: $YOUTUBE_API_KEY"

Une réponse raccourcie ressemble à ceci :

{
  "kind": "youtube#videoListResponse",
  "items": [
    {
      "id": "7lCDEYXw3mM",
      "snippet": { "title": "...", "channelTitle": "...", "publishedAt": "..." },
      "statistics": { "viewCount": "...", "likeCount": "..." }
    }
  ]
}

Le paramètre part est obligatoire et contrôle les sections qui sont renvoyées ; snippet, statistics, contentDetails et status sont ceux que vous utiliserez le plus souvent.

Maintenant une recherche, qui est l'appel que la plupart des gens recherchent. En Python avec requests :

import os
import requests

API_KEY = os.environ["YOUTUBE_API_KEY"]
BASE = "https://www.googleapis.com/youtube/v3"

resp = requests.get(
    f"{BASE}/search",
    params={"part": "snippet", "q": "api testing", "type": "video", "maxResults": 10},
    headers={"x-goog-api-key": API_KEY},
    timeout=10,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise SystemExit(f"{err['code']} {err['errors'][0]['reason']}: {err['message']}")

for item in resp.json()["items"]:
    print(item["id"]["videoId"], item["snippet"]["title"])

Pour search.list, part doit être snippet, maxResults est par défaut 5 et accepte de 0 à 50, et type est par défaut video,channel,playlist, donc réglez-le sur video si vous ne voulez que des vidéos. Les résultats de recherche contiennent videoId à l'intérieur de id, et non au niveau supérieur, c'est pourquoi la boucle ci-dessus lit item["id"]["videoId"].

Étape 6 : stockez la clé et exécutez la requête dans Apidog

Une variable shell fonctionne pour un script unique. Elle ne fonctionne pas pour une équipe et ne vous offre pas une vérification enregistrée et réexécutable. Voici la même requête dans Apidog, avec la clé conservée hors du cloud.

Créer un environnement. Ajoutez un environnement appelé YouTube avec deux variables : base_url défini sur https://www.googleapis.com/youtube/v3, et youtube_api_key. Pour la clé, laissez la valeur partagée comme espace réservé et collez la vraie clé dans le champ de valeur locale. Les valeurs locales restent dans le cache de votre client et ne sont jamais synchronisées avec vos coéquipiers ; la configuration complète se trouve dans notre guide sur les environnements et variables secrètes dans Apidog.
Construire la requête. Nouvelle requête, GET {{base_url}}/videos, paramètres de requête part=snippet,statistics et id=7lCDEYXw3mM, et un en-tête x-goog-api-key défini sur {{youtube_api_key}}. Sélectionnez l'environnement YouTube et envoyez. Vous devriez voir le même JSON que l'appel curl.
Transformer en test. Dans les post-processeurs de la requête, ajoutez des assertions : le statut est égal à 200, et $.items[0].id est égal à 7lCDEYXw3mM. Enregistrez la requête et ajoutez-la à un scénario de test. La vérification s'exécute maintenant à la demande, selon un calendrier, ou en CI via l'interface de ligne de commande Apidog, où --env-var "youtube_api_key=$YOUTUBE_API_KEY" injecte la clé au moment de l'exécution au lieu de la stocker.

Le bénéfice apparaît la première fois que la clé est renouvelée ou qu'une restriction change : réexécutez un scénario et vous saurez en quelques secondes si chaque appel YouTube fonctionne toujours. Téléchargez Apidog pour suivre ; c'est gratuit pour les équipes de quatre personnes maximum.

Quota et limites

L'API YouTube Data ne vous facture pas en dollars ; elle vous facture en unités de quota, et les chiffres proviennent de la page du calculateur de quota de Google. Chaque projet qui active l'API reçoit cette allocation par défaut :

Compartiment	Par défaut par jour	Coût par appel
`search.list`	100 appels	1 unité (compartiment propre)
`videos.insert`	100 appels	1 unité (compartiment propre)
Tous les autres points d'accès combinés	10 000 unités	varie, voir ci-dessous

Dans le pool partagé de 10 000 unités, les méthodes de liste telles que videos.list, channels.list, playlistItems.list et commentThreads.list coûtent 1 unité chacune. Les écritures coûtent plus cher : videos.update et videos.delete sont de 50 unités, et captions.insert est de 400. Quatre règles de la même page définissent comment vous devriez concevoir votre système en fonction de cela :

Les quotas sont réinitialisés à minuit, heure du Pacifique.
Chaque requête, y compris une requête invalide, coûte au moins 1 unité. Une boucle qui réessaie un mauvais appel consomme du quota pour rien.
Chaque page supplémentaire d'un résultat paginé coûte la même chose que la première page.
L'allocation par défaut est « sujette à changement ». Vérifiez la page, et non un tutoriel, avant de planifier la capacité.

Les guides plus anciens estimaient une recherche à 100 unités sur le pool de 10 000. La page actuelle place search.list dans son propre compartiment, donc le plafond est toujours de 100 recherches par jour, mais les recherches ne puisent plus dans le quota de vos autres appels.

Si cela ne suffit pas, la page d'audits de quota et de conformité vous oriente vers le formulaire d'extension de quota et d'audit des services API YouTube. Avant de le soumettre, mettez en cache les réponses, ne demandez que les valeurs part dont vous avez besoin, et regroupez les ID dans un seul appel videos.list (le paramètre id accepte une liste séparée par des virgules). L'utilisation est affichée sur la page Quotas de la Console Cloud.

Erreurs courantes et comment les corriger

La référence d'erreurs de Google liste les codes d'erreur de l'API. Les deux premières lignes ci-dessous proviennent de l'envoi de requêtes réelles à l'API en direct avec une mauvaise clé et sans clé.

HTTP	Raison	Message que vous verrez	Correction
400	`badRequest` (`API_KEY_INVALID`)	« Clé API non valide. Veuillez passer une clé API valide. »	Faute de frappe, clé supprimée ou restriction API qui exclut l'API YouTube Data v3. Recréez ou modifiez la clé.
403	`forbidden`	« La méthode n'autorise pas les appelants non enregistrés… »	Aucune clé n'a été envoyée. Ajoutez le paramètre `key` ou l'en-tête `x-goog-api-key`.
403	`quotaExceeded`	« La requête ne peut être complétée car vous avez dépassé votre quota. »	Attendez la réinitialisation à minuit PT, supprimez les appels redondants ou demandez une extension.
400	`missingRequiredParameter`	« Il manque un paramètre requis à la requête. »	Presque toujours un `part` manquant.
401	`authorizationRequired`	« La requête utilise le paramètre mine mais n'est pas correctement autorisée. »	Cet appel nécessite un jeton OAuth 2.0, pas une clé. Voir la FAQ.

Un dernier point tiré de l'expérience : si une restriction d'application ne correspond pas à l'appelant, vous obtenez une erreur 403 qui nomme le référent ou l'IP bloqué. Corrigez la restriction ou appelez depuis l'hôte autorisé. Et notez que les anciens fils de discussion de forum appellent l'erreur de clé invalide keyInvalid ; l'API en direct renvoie badRequest avec un détail API_KEY_INVALID, donc correspondez sur le message ou le détail, et non sur la chaîne de raison héritée.

FAQ

Une clé API YouTube est-elle gratuite ?

Oui. La création d'une clé ne coûte rien, et la documentation évalue l'API en unités de quota, et non en argent. L'allocation par défaut ci-dessus est ce que vous obtenez sans rien demander.

Quand ai-je besoin d'OAuth au lieu d'une clé API ?

Une clé API identifie votre projet et débloque les données publiques. Au moment où vous touchez des données utilisateur privées, ou insérez, mettez à jour ou supprimez quoi que ce soit, Google exige un jeton OAuth 2.0 de l'utilisateur qui possède ces données. Noter une vidéo, lister vos propres abonnements ou utiliser le filtre mine=true relèvent tous du côté OAuth. Notre comparaison des clés API et des jetons d'authentification explique pourquoi les deux identifiants répondent à des questions différentes.

Un agent IA peut-il utiliser ma clé API YouTube ?

Oui, tant que l'agent s'exécute là où les restrictions de la clé le permettent. Un serveur YouTube MCP est un moyen de transmettre des données vidéo à un assistant de codage ; donnez-lui une clé restreinte à l'API Data et à la machine sur laquelle il s'exécute, et gardez-la hors de l'invite elle-même.

Que faire si la clé fuit ?

Supprimez-la dans la page Identifiants et créez un remplacement. Ensuite, corrigez la source : déplacez la clé vers une valeur locale dans Apidog ou un magasin de secrets, et analysez le dépôt afin que l'ancienne clé ne reste pas dans l'historique.

Étape suivante

Vous avez maintenant un projet, une API activée, une clé restreinte et une requête qui fonctionne depuis curl, Python et Apidog. Intégrez le scénario enregistré dans votre CI et laissez la page Quotas vous indiquer quand il est temps d'optimiser.