L'API de Transcriptions YouTube ne fonctionne pas ? Liste de diagnostic
Toutes les vraies raisons pour lesquelles une requête de transcription échoue, basées sur les issues les plus discutées de la communauté open-source elle-même - pas des suppositions - plus le code d'erreur exact et la solution pour chacune.
Liste de diagnostic
Comparez votre code d'erreur (ou la forme de votre réponse) au tableau ci-dessous.
| Code | Ce que ça veut dire | Que faire |
|---|---|---|
MISSING_URL / INVALID_URL · 400 | Le paramètre v est manquant, ou n'est pas un ID/URL de vidéo que YouTube reconnaît. | Passez un ID vidéo valide de 11 caractères ou une URL complète youtube.com/watch?v=... |
VIDEO_UNAVAILABLE · 404 | La vidéo est privée, supprimée, ou bloquée par région - elle n'existe pas du point de vue du serveur. | Vérifiez d'abord que la vidéo se charge dans un navigateur normal. Si ce n'est pas le cas, il n'y a rien qu'une API puisse récupérer. |
TRANSCRIPT_DISABLED · 404 | Signifie généralement que l'auteur a désactivé les sous-titres - mais les blocages régionaux et d'IP peuvent produire une erreur d'apparence identique. | Voir l'encadré ci-dessous avant de supposer que c'est permanent. |
LANGUAGE_NOT_AVAILABLE · 404 | La vidéo a des sous-titres, juste pas dans la langue demandée. | Retirez le paramètre de langue pour obtenir ce qui est disponible, ou consultez d'abord la liste des sous-titres de la vidéo. |
TRANSCRIPT_NOT_FOUND · 404 | Aucune transcription n'existe dans aucune langue pour cette vidéo. | Comme pour les sous-titres désactivés - rien à récupérer. Toutes les vidéos n'en ont pas. |
RATE_LIMITED · 429 | Votre clé API a fait plus de requêtes que la limite par minute de votre offre ne le permet. | Ralentissez et réessayez, ou passez à une offre avec une limite plus élevée. |
UPSTREAM_* · 429/503/504 | Un problème transitoire en parlant à YouTube lui-même, pas à votre clé ou votre requête. | Sans risque de réessayer après un court délai - exactement le genre de panne qu'une API hébergée absorbe à votre place. |
"Sous-titres désactivés" ne veut pas toujours dire désactivés
L'issue la plus discutée de toute l'histoire de youtube-transcript-api open-source (187 commentaires) concerne un script qui lève "TranscriptsDisabled" pour une vidéo qui n'est pas réellement désactivée - elle affiche les sous-titres sans problème dans un navigateur normal. Trois causes réelles différentes produisent une erreur quasi identique :
- Réellement désactivés - l'auteur a coupé les sous-titres. Rien à récupérer, dans aucune langue.
- Bloqué par région - la vidéo ou ses sous-titres ne sont pas disponibles depuis le pays de votre serveur, mais fonctionnent depuis un navigateur dans une autre région.
- Bloqué par IP - YouTube renvoie un échec générique plutôt qu'un échec spécifique, et la vraie cause est le problème d'hébergement cloud ci-dessous.
Une erreur brute de parsing XML ("no element found", "line 1, column 0") au lieu d'une exception propre relève de la même famille de problème - un corps de réponse vide, généralement dû au même blocage IP ou à PoToken ci-dessous, pas un bug dans le code de parsing lui-même.
Bloqué sur AWS, GCP, Azure, ou un VPS ?
Si un script fonctionne parfaitement sur votre ordinateur portable puis échoue dès qu'il est déployé sur un serveur cloud, c'est presque toujours pour cette raison : le endpoint de récupération de sous-titres de YouTube bloque des plages entières d'IP de datacenters, pas seulement des IP individuelles abusives. L'espace IP de chaque grand fournisseur cloud finit par être touché, car des milliers de scripts sans rapport entre eux partagent les mêmes plages d'adresses.
Could not retrieve a transcript for the video https://www.youtube.com/watch?v=...!
This is most likely caused by:
YouTube is blocking requests from your IP.Des solutions réalistes, à peu près dans l'ordre de l'effort :
- Faire transiter les requêtes par un pool de proxies résidentiels ou mobiles - fonctionne parfois, mais les signalements de configurations résidentielles rotatives payantes qui échouent quand même sont de plus en plus fréquents. Pas une solution permanente.
- Alterner entre plusieurs fournisseurs cloud ou régions - gagne du temps jusqu'à ce que ces plages soient elles aussi signalées.
- Mettre en cache de façon agressive pour ne pas refaire de requêtes sur les mêmes vidéos - réduit la fréquence du blocage, ne l'élimine pas.
- Utiliser une API hébergée qui gère déjà cette infrastructure - le problème passe de 'votre projet' à 'quelqu'un dont le vrai travail est de maintenir ça fonctionnel'.
C'est exactement le vide que comble notre propre API de Transcriptions YouTube - pas une bibliothèque différente, mais une infrastructure déjà construite spécifiquement pour ce problème.
Vous obtenez PoTokenRequired ?
Une panne plus récente : le endpoint de sous-titres de YouTube exige de plus en plus un jeton de preuve d'origine généré à l'exécution par son propre JavaScript du lecteur - pas un cookie, pas une vérification de réputation IP, une valeur cryptographique. Une simple requête HTTP n'a aucun moyen d'en produire un.
Voir le détail technique réel dans jdepoix/youtube-transcript-api#592 - à la date de ce rapport, il n'existe aucune solution de contournement documentée dans la bibliothèque open-source.
C'est exactement le genre de problème qu'une API hébergée est censée absorber - appelez un endpoint et obtenez une transcription ou une erreur claire, sans avoir à résoudre vous-même la génération du jeton.
Ce que notre propre API renvoie pour chaque échec
Si vous utilisez déjà notre API et voulez traiter l'échec exact plutôt que de deviner à partir du seul statut HTTP, chaque erreur revient avec un champ `code` stable :
curl "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ" \
-H "Authorization: Bearer sk_live_..."
# A failure looks like:
# { "success": false, "code": "TRANSCRIPT_DISABLED", "message": "Transcripts are disabled for this video." }La référence complète des paramètres et tous les codes de statut sont dans la documentation de l'API.
Erreurs courantes de l'API de Transcriptions YouTube
Pourquoi j'obtiens 'YouTube is blocking requests from your IP' ?
Vous appelez le endpoint de sous-titres de YouTube depuis une adresse IP cloud/datacenter (AWS, GCP, Azure, un VPS...), et YouTube bloque ces plages plus agressivement que les IP résidentielles. Ce n'est généralement pas personnel - c'est toute la plage IP, partagée avec des milliers d'autres scripts.
Pourquoi mon script fonctionne en local mais échoue une fois déployé ?
Votre ordinateur portable a une IP résidentielle ; votre serveur a une IP de datacenter. Même code, réputation réseau différente - la cause la plus courante de 'ça marche ici, ça échoue là' pour quiconque héberge sa propre bibliothèque de transcription YouTube.
Pourquoi 'sous-titres désactivés' s'avère parfois faux ?
Parce que YouTube ne renvoie pas toujours une raison précise - un blocage régional ou IP peut produire la même erreur générique qu'une vidéo réellement désactivée. Vérifiez si la vidéo affiche des sous-titres dans un navigateur normal depuis un autre réseau avant de supposer qu'elle est indisponible en permanence.
Qu'est-ce que PoTokenRequired ?
YouTube exigeant un jeton de preuve d'origine généré par le vrai JavaScript du lecteur à l'exécution, pas une valeur statique qu'on peut coder en dur ou extraire une fois. Les simples requêtes HTTP - et la plupart des bibliothèques de scraping - n'ont aucun moyen d'en générer un, d'où l'absence actuelle de solution documentée dans la bibliothèque open-source.
Pourquoi n'y a-t-il pas de transcription dans la langue demandée ?
La vidéo a des sous-titres, juste pas dans cette langue. Faites la requête sans paramètre de langue pour obtenir ce qui est disponible, ou vérifiez d'abord quelles langues existent.
Comment éviter les limites de débit ?
Deux limites différentes existent : le plafond de requêtes par minute de votre offre (passez à une offre supérieure), et les limites propres à YouTube (sans risque de réessayer après un court délai - une API hébergée absorbe l'essentiel de ça pour vous).