youtube-transcript-api это бесплатная библиотека Python с открытым кодом, которая получает субтитры видео с YouTube: pip install youtube-transcript-api, затем YouTubeTranscriptApi().fetch(video_id). С вашего компьютера она работает хорошо, но с облачного сервера YouTube часто блокирует её ошибками RequestBlocked или IpBlocked, и с видео без субтитров она не поможет.
Мы запустили её с облачной машины 21 ноября 2026 года, а затем пропустили те же два видео через наш собственный размещённый API с той же машины. Ниже что произошло в каждом случае, как пользоваться библиотекой и когда размещённый API подходит лучше.
Что такое youtube-transcript-api?
Это библиотека Python от Jonas Depoix, на GitHub и PyPI, под лицензией MIT. Актуальная версия 1.2.5, для Python 3.8 и новее.
- Она читает субтитры, которые у YouTube уже есть: собственные субтитры канала или автоматические.
- Ей не нужны ни ключ API, ни headless-браузер.
- Она умеет показывать языки субтитров видео, предпочитать один язык другому и использовать машинный перевод YouTube.
- Она выдаёт текст, JSON, SRT или WebVTT и имеет утилиту командной строки.
README честно говорит о компромиссе: библиотека использует недокументированную часть веб-плеера YouTube, поэтому «no guarantee that it won't stop working tomorrow».
Как ею пользоваться?
pip install youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import SRTFormatter
ytt_api = YouTubeTranscriptApi()
# English if it exists, else German
transcript = ytt_api.fetch("aircAruvnKk", languages=["en", "de"])
for snippet in transcript:
print(snippet.start, snippet.text)
print(SRTFormatter().format_transcript(transcript))
В командной строке то же самое делает youtube_transcript_api aircAruvnKk --languages en --format json > transcript.json. В README описаны список языков, перевод и остальное.
Почему на моём сервере она падает с IpBlocked?
Потому что YouTube блокирует большинство запросов от облачных провайдеров. README библиотеки говорит прямо: YouTube «has started blocking most IPs that are known to belong to cloud providers (like AWS, Google Cloud Platform, Azure, etc.)», так что после развёртывания вы «most likely» получите ошибки RequestBlocked или IpBlocked. Домашний IP тоже могут заблокировать после слишком большого числа запросов.
Мы увидели это сами. 21 ноября 2026 года мы установили версию 1.2.5 на облачную машину и запросили две открытые лекции:
Та же машина, те же два видео, 21 ноября 2026 года (UTC).
Оба вызова вернули IpBlocked примерно через 1,1 секунды. Обычный запрос к youtube.com с этой машины перенаправлялся на страницу Google о «необычном трафике», то есть машину отклонял сам YouTube, а не ошибка библиотеки.
Решение из README это прокси, причём рекомендуются ротируемые резидентные, потому что статические прокси YouTube банит после длительного использования. Это работает, но означает ещё один платный сервис, ещё один аккаунт и блокировки, за которыми надо следить.
Что ещё может её остановить?
- Нет субтитров. Библиотека читает субтитры; звук она не расшифровывает. Отключённые субтитры дают
TranscriptsDisabled, отсутствующий язык даётNoTranscriptFound. - Видео с возрастным ограничением. README сообщает, что вход через cookies, который для них нужен, «currently not available» после изменений на стороне YouTube.
- Изменения на YouTube. Поскольку библиотека использует недокументированный интерфейс, обновление YouTube может сломать её до выхода новой версии.
Ничто из этого не мешает использовать её для скрипта на ноутбуке. Но это стоит учесть до того, как встраивать её в продукт.
Чем заменить её, когда она заблокирована?
Размещённым API расшифровки, который получает данные на своей стороне. Наш это API YouTubeTranscript.dev. С той же облачной машины, за несколько минут до этого, те же два видео:
| Видео | Длина | Время | Слов | Строк с таймкодом | Кредиты |
|---|---|---|---|---|---|
| But what is a neural network? (3Blue1Brown) | 18:40 | 4,2 секунды | 3 357 | 286 | 1 |
| 1. What is Computation? (MIT OpenCourseWare) | 43:06 | 4,2 секунды | 6 363 | 887 | 1 |
| То же видео 3Blue1Brown, запрошенное повторно | 18:40 | 1,3 секунды | 3 357 | 286 | 0 |
Как мы измеряли: по одному запросу к POST /api/v2/transcribe, только субтитры, с таймкодами, время засекал curl от отправки до полного ответа. Кредиты указаны так, как их сообщил каждый ответ. По одному прогону, так что время это пример.
Вызов из Python:
import requests
r = requests.post(
"https://www.youtubetranscript.dev/api/v2/transcribe",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"video": "aircAruvnKk", "mode": "auto", "format": {"timestamp": True}},
)
data = r.json()["data"]
for seg in data["transcript"]["segments"]:
print(seg["start"], seg["text"]) # start and end are in milliseconds
Компромисс в стоимости: библиотека бесплатна, а API стоит 1 кредит за видео с субтитрами, с 10 бесплатными кредитами в месяц и платными тарифами от 5 долларов за 500. С "mode": "auto" он расшифровывает и видео без субтитров, по 1 кредиту за 2 минуты звука. Если не хотите писать запрос сами, есть Python SDK.
Как встроить API расшифровки в свой продукт?
Одна и та же схема работает с любым API:
- Держите ключ на сервере. Пользователи отправляют ссылку на ваш бэкенд, а бэкенд вызывает API. Никогда не кладите ключ в код браузера или приложения.
- Принимайте любой формат ссылки. Передавайте ссылку так, как её ввёл пользователь; наш API принимает полные URL, youtu.be, Shorts, embed-ссылки и голые ID (полный список).
- Сохраняйте расшифровку по ID видео. Большинство продуктов снова и снова запрашивают одни и те же популярные видео. У нас расшифровка, которая уже есть у вашего аккаунта, при повторном запросе ничего не стоит, как видно в третьей строке, но локальная копия ещё быстрее.
- Обрабатывайте видео без субтитров как задание. Расшифровка звука занимает больше времени, чем стоит ждать веб-запросу. Отправьте
mode: "auto"сwebhook_urlили опрашивайте возвращённый ID задания, а пользователю показывайте прогресс. - Используйте пакеты, когда видео много. Для плейлиста, канала или накопившейся очереди используйте пакетный эндпоинт вместо цикла одиночных вызовов, чтобы не выйти за лимит запросов.
В документации API описано каждое поле, а наш гид по API распознавания речи измеряет точность и стоимость на звуке без субтитров.
Что выбрать?
| Если вы... | Используйте |
|---|---|
| запускаете скрипт на своём компьютере, по нескольку видео | youtube-transcript-api |
| развёртываете на облачном сервере, в serverless-функции или в продукте | Размещённый API или библиотеку плюс ротируемые резидентные прокси |
| работаете с видео без субтитров | Сервис, который расшифровывает звук |
| получаете целые плейлисты или каналы | Размещённый API с пакетным эндпоинтом |
Итог
- youtube-transcript-api бесплатна, под лицензией MIT и проста:
YouTubeTranscriptApi().fetch(video_id). - На облачном сервере YouTube часто её блокирует; на нашей облачной машине оба видео дали
IpBlockedпримерно через 1,1 секунды. Предлагаемое решение это прокси. - Она читает только существующие субтитры, а видео с возрастным ограничением пока недоступны.
- Размещённый API вернул те же видео с той же машины за 4,2 секунды каждое, по 1 кредиту, и умеет работать с видео без субтитров.
Частые вопросы
Что такое youtube-transcript-api?+
Библиотека Python с открытым кодом (лицензия MIT), которая получает субтитры, уже имеющиеся у видео на YouTube, включая автоматические, без ключа API и без браузера. Установка: pip install youtube-transcript-api, вызов: YouTubeTranscriptApi().fetch(video_id).
Почему youtube-transcript-api выдаёт RequestBlocked или IpBlocked?+
Потому что YouTube блокирует большинство запросов с IP-адресов облачных провайдеров и может заблокировать любой IP, который делает слишком много запросов. Об этом пишет сам README библиотеки и советует ротируемые резидентные прокси. С нашей облачной машины 21 ноября 2026 года оба проверенных видео дали IpBlocked примерно через 1,1 секунды.
Может ли youtube-transcript-api расшифровать видео без субтитров?+
Нет. Он читает уже существующие субтитры. Видео с отключёнными субтитрами вызывает TranscriptsDisabled, видео без вашего языка вызывает NoTranscriptFound. Чтобы получить текст из звука, нужен сервис распознавания речи.
youtube-transcript-api бесплатный?+
Да, библиотека бесплатна и распространяется по лицензии MIT. На сервере обычно приходится платить за прокси, потому что облачные IP блокируются.
Чем заменить youtube-transcript-api на сервере?+
Размещённым API расшифровки, который сам получает субтитры. С той же машины, где библиотеку заблокировали, API YouTubeTranscript.dev вернул оба видео за 4,2 секунды каждое, по 1 кредиту, а повторный запрос за 1,3 секунды бесплатно.
Как встроить API расшифровки в свой продукт?+
Храните ключ API на сервере, отправляйте ссылку на видео в один эндпоинт, сохраняйте расшифровку по ID видео, чтобы не платить дважды, обрабатывайте видео без субтитров как асинхронное задание с вебхуком и используйте пакетный эндпоинт для множества видео.