API для скачивания видео с YouTube

Почему не yt-dlp на своём сервере

Скачать одно видео с YouTube несложно. Сложно делать это тысячи раз в день и не останавливаться: YouTube регулярно меняет отдачу, начинает требовать подтверждение «вы не робот», блокирует адреса дата-центров. Приходится следить за этим каждый день, обновлять загрузчик после каждого изменения на стороне площадки и разбирать ночные падения.

Отдельная история — нагрузка. Пользователи приходят волнами, а сервер под пик простаивает в остальное время. Плюс трафик: каждое видео нужно сначала скачать к себе, потом отдать дальше.

Мы живём с этим уже несколько лет: через API проходит 4,4 млн скачиваний в месяц, к нему подключено 56 ботов. Загрузку мы доводим до конца сами — в ответе приходит либо готовый файл, либо понятная причина отказа, и за ошибку поинты не списываются. Всё, что уже скачивали раньше, отдаётся из кэша.

Что умеет API

Все методы — обычные GET-запросы с токеном в заголовке. Ответы в JSON, субтитры — текстом.

• Данные о видео: название, описание, длительность, канал, счётчики просмотров и лайков, превью.
• Список доступных форматов с отметкой, какие уже лежат в кэше; для остальных — размер файла.
• Скачивание в выбранном качестве до 1080p включительно.
• Выбор языка озвучки для роликов с несколькими аудиодорожками.
• Субтитры: список дорожек и текст в формате txt или srt.
• Поиск по YouTube — видео или каналы.
• Данные о канале и лента его последних видео.

Как выглядит интеграция

Токен передаётся в заголовке X-Token. Если к аккаунту подключено несколько ботов, добавляется заголовок X-Bot-Id — он говорит, какому из ботов доставить файл.

Скачивание асинхронное. Первый запрос GET /video/{id}/download/{format} ставит задачу в очередь и возвращает status: queued. Дальше вы повторяете тот же запрос раз в пять-семь секунд, пока не получите status: ready вместе с file_id. Если файл уже в кэше, file_id приходит в первом же ответе.

Полученный file_id ваш бот передаёт в sendVideo или sendAudio — файл уходит пользователю напрямую из Telegram, минуя ваш сервер. Примеры на curl и Python собраны в быстром старте.

Сколько это стоит

Расчёт ведётся в поинтах: 1 000 поинтов равны 1 $. Скачивание стоит 10 поинтов, то есть 0,01 $, а в пересчёте на тысячу — 10 $. Повторная отдача ролика, который ваш бот уже получал, — 2 поинта, 2 $ за тысячу. Данные о видео — 1 поинт, поиск — 5.

Списание происходит только за успешные ответы. Недоступное видео, ошибка параметра или сбой на нашей стороне баланс не трогают, а запросы статуса загрузки бесплатны.

Пополнение начинается с 5 $. При регистрации на балансе уже лежат 200 поинтов — хватит на 20 скачиваний, чтобы собрать интеграцию и проверить её на реальных роликах. Карта для этого не нужна.

Общий кэш: выигрыш во времени

В кэше около 95 миллионов готовых файлов, и он общий: его пополняет каждое скачивание — ваше или чужое. Популярный ролик почти наверняка уже там, поэтому тянуть его с YouTube заново не нужно и file_id приходит в первом же ответе.

На цену это не влияет: ролик, которого ваш бот ещё не получал, стоит полную цену, даже если он лежит в кэше. Причина в том, что file_id в Telegram привязан к боту, и файл всё равно нужно передать вашему. Льготные 2 поинта списываются за повторную отдачу ролика, который ваш бот уже получал.

Ответ на запрос форматов помечает лежащие в кэше варианты флагом cached, поэтому ваш бот может заранее показать пользователю, что придёт сразу, а что придётся подождать. Предсказывать по этому флагу списание нельзя: он про скорость.

Ограничения, о которых стоит знать заранее

Поддерживается только YouTube. Максимальное качество — 1080p. В цепочке доставки нужен Telegram-бот: файл приходит как file_id, а не как прямая ссылка. Автономный режим без Telegram и другие площадки мы открываем по запросу — сначала измеряем спрос, потом строим.

Вопросы по теме