API расшифровок YouTube не работает? Диагностический чек-лист
Все реальные причины, по которым запрос расшифровки не удаётся, составлены на основе самых обсуждаемых issue самого open-source сообщества - не догадок - плюс точный код ошибки и решение для каждой.
Диагностический чек-лист
Сопоставьте свой код ошибки (или форму ответа) с таблицей ниже.
| Код | Что означает | Что делать |
|---|---|---|
MISSING_URL / INVALID_URL · 400 | Параметр v отсутствует, или это не ID/URL видео, который распознаёт YouTube. | Передайте корректный 11-символьный ID видео или полный URL youtube.com/watch?v=... |
VIDEO_UNAVAILABLE · 404 | Видео приватное, удалено, или заблокировано по региону - с точки зрения сервера его не существует. | Сначала убедитесь, что видео загружается в обычном браузере. Если нет - API нечего получать. |
TRANSCRIPT_DISABLED · 404 | Обычно означает, что автор отключил субтитры - но региональные блокировки и блокировки по IP могут давать точно такую же ошибку. | Смотрите пояснение ниже, прежде чем считать это постоянным. |
LANGUAGE_NOT_AVAILABLE · 404 | У видео есть субтитры, просто не на запрошенном языке. | Уберите параметр языка, чтобы получить то, что доступно, или сначала проверьте собственный список субтитров видео. |
TRANSCRIPT_NOT_FOUND · 404 | Для этого видео не существует расшифровки ни на одном языке. | То же самое, что и отключённые субтитры - получать нечего. Не у каждого видео это есть. |
RATE_LIMITED · 429 | Ваш API-ключ сделал больше запросов, чем разрешает лимит в минуту вашего тарифа. | Снизьте частоту и повторите попытку, либо перейдите на более высокий лимит. |
UPSTREAM_* · 429/503/504 | Временная проблема при обращении к самому YouTube, а не к вашему ключу или запросу. | Безопасно повторить попытку после небольшой паузы - именно такой сбой хостинговый API берёт на себя вместо вас. |
"Расшифровка отключена" не всегда означает отключена
Самый обсуждаемый issue за всю историю open-source youtube-transcript-api (187 комментариев) - это скрипт, выдающий "TranscriptsDisabled" для видео, которое на самом деле не отключено - субтитры нормально воспроизводятся в обычном браузере. Три разные реальные причины дают почти идентичную ошибку:
- Действительно отключено - автор выключил субтитры. Получать нечего, ни на одном языке.
- Заблокировано по региону - видео или его субтитры недоступны из страны вашего сервера, но работают из браузера в другом регионе.
- Заблокировано по IP - YouTube возвращает общую ошибку вместо конкретной, а реальная причина - проблема с облачным хостингом ниже.
Необработанная ошибка парсинга XML ("no element found", "line 1, column 0") вместо чистого исключения - из той же категории проблем: пустое тело ответа, обычно по той же причине блокировки IP или PoToken ниже, а не баг в самом коде парсинга.
Заблокировано на AWS, GCP, Azure или VPS?
Если скрипт прекрасно работает на вашем ноутбуке, а затем перестаёт работать сразу после развёртывания на облачном сервере, почти всегда причина в этом: эндпоинт получения субтитров YouTube блокирует целые диапазоны IP дата-центров, а не только отдельные злоупотребляющие IP. Пространство IP каждого крупного облачного провайдера рано или поздно попадает под это, потому что тысячи не связанных друг с другом скриптов используют одни и те же диапазоны адресов.
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.Реалистичные способы обойти это, примерно в порядке трудозатрат:
- Направлять запросы через пул резидентных или мобильных прокси - иногда работает, но всё чаще встречаются сообщения, что даже платные ротируемые резидентные настройки продолжают давать сбой. Не постоянное решение.
- Чередовать несколько облачных провайдеров или регионов - даёт время, пока эти диапазоны тоже не пометят.
- Агрессивно кэшировать, чтобы не запрашивать одни и те же видео повторно - снижает частоту блокировок, но не устраняет их.
- Использовать хостинговый API, который уже поддерживает эту инфраструктуру - проблема переходит от "вашего проекта" к "тому, чья реальная работа - поддерживать это в рабочем состоянии".
Именно этот реальный пробел закрывает наш собственный API расшифровок YouTube - не другая библиотека, а инфраструктура, уже построенная именно под эту проблему.
Получаете PoTokenRequired?
Более новый вид сбоя: эндпоинт субтитров YouTube всё чаще требует токен подтверждения происхождения, генерируемый во время выполнения собственным JavaScript плеера - не cookie, не проверка репутации IP, а криптографическое значение. У обычного HTTP-запроса нет способа его сгенерировать.
Реальные технические подробности смотрите в jdepoix/youtube-transcript-api#592 - на момент этого отчёта в open-source библиотеке нет задокументированного обхода.
Это именно тот тип проблемы, который должен брать на себя хостинговый API - вызовите один эндпоинт и получите расшифровку или понятную ошибку, не решая генерацию токена самостоятельно.
Что возвращает наш собственный API при каждом сбое
Если вы уже используете наш API и хотите ветвиться по точному сбою, а не гадать только по HTTP-статусу, каждая ошибка возвращается со стабильным полем `code`:
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." }Полный справочник по параметрам и все коды состояния есть в документации API.
Частые ошибки API расшифровок YouTube
Почему я получаю 'YouTube is blocking requests from your IP'?
Вы вызываете эндпоинт субтитров YouTube с облачного/дата-центрового IP-адреса (AWS, GCP, Azure, VPS...), и YouTube блокирует такие диапазоны агрессивнее, чем домашние/резидентные IP. Обычно это не личное - это весь диапазон IP, общий с тысячами других скриптов.
Почему мой скрипт работает локально, но падает после развёртывания?
У вашего ноутбука резидентный IP; у вашего сервера - IP дата-центра. Тот же код, другая репутация сети - самая частая причина "здесь работает, там падает" для тех, кто самостоятельно хостит библиотеку расшифровок YouTube.
Почему 'расшифровка отключена' иногда оказывается неверной?
Потому что YouTube не всегда возвращает конкретную причину - региональная блокировка или блокировка по IP может дать ту же общую ошибку, что и действительно отключённое видео. Проверьте, воспроизводит ли видео субтитры в обычном браузере из другой сети, прежде чем считать его недоступным навсегда.
Что такое PoTokenRequired?
YouTube требует токен подтверждения происхождения, генерируемый настоящим JavaScript плеера во время выполнения, а не статическое значение, которое можно захардкодить или извлечь один раз. У обычных HTTP-запросов - и у большинства библиотек скрапинга - нет способа его сгенерировать, поэтому сейчас в open-source библиотеке нет задокументированного обхода.
Почему нет расшифровки на языке, который я запросил?
У видео есть субтитры, просто не на этом языке. Запросите без параметра языка, чтобы получить то, что доступно, или сначала проверьте, какие языки существуют.
Как избежать лимитов частоты запросов?
Есть два разных лимита: собственный предел запросов в минуту вашего тарифа (перейдите на более высокий), и собственные лимиты YouTube на стороне upstream (безопасно повторить попытку после небольшой паузы - хостинговый API берёт на себя большую часть этого за вас).