От токена до первого файла
Это не полная документация, а короткий путь к работающей интеграции: получить токен, сделать первый запрос, скачать видео и отправить его пользователю. Остальные методы — в таблице ниже.
1. Получите токен
Всё делается в кабинете, без переписки с поддержкой.
Шаг 1
Войдите через Telegram
Нажмите «Войти» и подтвердите вход в Telegram. Пароля нет; аккаунт создаётся при первом входе, и на нём уже лежат 200 пробных поинтов.
Шаг 2
Добавьте бота
Укажите @username бота, которому будут доставляться файлы. Токен BotFather не нужен. Пока бот не подтверждён, запросы от его имени не выполняются — обычно это занимает меньше минуты.
Шаг 3
Выпустите токен API
Токен показывается целиком один раз, при создании. Сохраните его в секретах приложения; в кабинете потом видна только маскированная форма. Скомпрометированный токен можно отозвать и выпустить новый.
Токен — это доступ к балансу
2. Авторизация
Токен передаётся в заголовке X-Token с каждым запросом. Базовый адрес API — https://api.massbots.xyz.
Проверка баланса — самый простой первый запрос
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/me/balance"{
"balance": 4980,
"bot_name": "my_downloader_bot",
"bot_id": 123456789,
"customer_id": 42
}Несколько ботов на одном аккаунте
Если к аккаунту подключено больше одного бота, каждый запрос должен содержать заголовок X-Bot-Id с числовым идентификатором бота — так мы знаем, кому доставлять файл. Без него запрос отклоняется как неавторизованный. С одним ботом заголовок не нужен.
curl -H "X-Token: $MASSBOTS_TOKEN" \
-H "X-Bot-Id: 123456789" \
"https://api.massbots.xyz/me/balance"3. Примеры запросов
Все методы — GET. Идентификатор видео — тот же, что в адресе YouTube после v=.
Данные о видео
1 поинт. Удобно для карточки перед скачиванием: название, длительность, канал.
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/video/dQw4w9WgXcQ"Ответ (сокращённо)
{
"id": "dQw4w9WgXcQ",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up",
"duration": "3:33",
"channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"channel_title": "Rick Astley",
"view_count": 1600000000,
"like_count": 18000000,
"published_at": "2009-10-25T06:57:33Z",
"thumbnails": { "...": "..." }
}Форматы и скачивание
Сначала запросите список форматов — он бесплатный. Ключи объекта — доступные качества; поле cached говорит, что файл уже лежит в нашем общем кэше: скачивать его с YouTube заново не придётся, поэтому ready и file_id придут в первом же ответе. У таких форматов file_size не возвращается — размер известен только для тех, что ещё предстоит скачать. Поле voices перечисляет дорожки озвучки, если у ролика их несколько.
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/video/dQw4w9WgXcQ/formats"{
"360p": { "format": "360p", "cached": true },
"720p": { "format": "720p", "cached": false, "file_size": 48213377,
"voices": { "ru": { "cached": true }, "en": { "cached": false } } },
"1080p": { "format": "1080p", "cached": false, "file_size": 112034562 }
}cached — это про скорость, а не про цену
cached: true. Льготные 2 поинта списываются только за повторную отдачу ролика, который ваш бот уже получал. Планировать расход по этому флагу нельзя; фактические списания видны в статистике и в кабинете.Скачивание асинхронное. Один и тот же запрос запускает загрузку и возвращает её статус: queued — задача в очереди, downloading — в работе, ready — готово, в ответе есть file_id. Повторяйте запрос раз в пять-семь секунд: при более частом опросе API вернёт downloading с подсказкой о рекомендуемой паузе в поле message. Если файл был в общем кэше, readyприходит сразу.
# Первый вызов ставит задачу в очередь…
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/video/dQw4w9WgXcQ/download/720p"
# → {"status": "queued"}
# …тот же вызов через несколько секунд возвращает статус.
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/video/dQw4w9WgXcQ/download/720p"
# → {"status": "downloading"}
# → {"status": "ready", "file_id": "BAACAgIAAxkBAAI..."}
# Русская озвучка, если она есть в voices:
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/video/dQw4w9WgXcQ/download/720p?lang=ru"Python: скачать и отправить пользователю
Полный цикл на стандартной библиотеке requests. Функция возвращает file_id, который передаётся в sendVideo любой библиотекой Bot API.
import os
import time
import requests
API = "https://api.massbots.xyz"
HEADERS = {"X-Token": os.environ["MASSBOTS_TOKEN"]}
# Если к аккаунту подключено несколько ботов:
# HEADERS["X-Bot-Id"] = os.environ["BOT_ID"]
def download(video_id: str, fmt: str = "720p", lang: str | None = None) -> str:
"""Запускает скачивание и ждёт file_id, готовый для sendVideo."""
params = {"lang": lang} if lang else None
while True:
r = requests.get(
f"{API}/video/{video_id}/download/{fmt}",
headers=HEADERS,
params=params,
timeout=30,
)
if r.status_code != 200:
# 4xx — проблема запроса или баланса, 500 — загрузка не удалась.
raise RuntimeError(r.json().get("error", r.text))
data = r.json()
if data["status"] == "ready":
return data["file_id"]
# queued или downloading — опрашиваем раз в несколько секунд.
time.sleep(6)
file_id = download("dQw4w9WgXcQ", "720p")
# Дальше — ваш бот, любой библиотекой Bot API:
# bot.send_video(chat_id=user_id, video=file_id)Поиск
5 поинтов за запрос, до 25 результатов. Ответ — массив тех же объектов, что возвращает метод данных о видео или канале.
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/search?q=never+gonna+give+you+up&kind=video"
# kind=channel — искать каналы. Без kind ищутся видео.Субтитры
Список дорожек бесплатен, текст дорожки — 1 поинт. Формат txt отдаёт чистый текст, srt — с таймкодами.
# Список дорожек (бесплатно)
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/video/dQw4w9WgXcQ/subtitles"
# Текст дорожки в формате srt (txt — по умолчанию)
curl -H "X-Token: $MASSBOTS_TOKEN" \
"https://api.massbots.xyz/video/dQw4w9WgXcQ/subtitles/en?f=srt"4. Как файл попадает к пользователю
Ваш сервер не скачивает видео и не загружает его в Telegram — он передаёт идентификатор.
Файл доставляется вашему боту
Telegram привязывает file_id к конкретному боту, поэтому готовый файл доставляется вашему боту внутри Telegram. В ответе API вы получаете идентификатор, который принадлежит именно ему.
Бот отправляет по file_id
Вызовите sendVideo (или sendAudio) с этим идентификатором — как с любым файлом, который уже есть в Telegram. Загрузки с вашей стороны нет, трафика тоже.
Повторная отдача — дешевле
Ролик, который ваш бот уже получал в этом формате, в следующий раз отдаётся сразу и стоит 2 поинта. Тот же ролик, заказанный кем-то другим, вашему боту всё равно нужно передать — это полная цена. Сохранять file_id у себя не обязательно, но можно.
Все методы
Стоимость — в поинтах за успешный ответ. Прочерк означает, что метод бесплатный. Цены в долларах — на странице цен.
| Метод | Описание | Параметры | Поинтов |
|---|---|---|---|
GET /me/balance | Текущий баланс токена, имя и идентификатор бота, от которого сделан запрос. | — | — |
GET /me/stats | Списания по дням и типам запросов за последнюю неделю. | — | — |
GET /video/{id} | Данные о видео: название, описание, длительность, канал, счётчики, превью. | — | 1 |
GET /video/{id}/formats | Доступные форматы с отметкой cached (файл есть в общем кэше), списком дорожек озвучки и размером файла — он возвращается только у форматов, которых в кэше нет. | — | — |
GET /video/{id}/download/{format} | Запускает скачивание и возвращает статус. Тем же запросом опрашивается готовность. | lang — язык озвучки, например ru или en | 102 за повторную отдачу, 12 за 1080p |
GET /video/{id}/subtitles | Список доступных дорожек субтитров. | — | — |
GET /video/{id}/subtitles/{lang} | Текст субтитров на выбранном языке. | f — формат: txt (по умолчанию) или srt | 1 |
GET /search | Поиск по YouTube, до 25 результатов. | q — запрос; kind — video (по умолчанию) или channel | 5 |
GET /channel/{id} | Данные о канале. | — | 1 |
GET /channel/{id}/feed | Лента последних видео канала. | — | — |
Как считаются списания
- Только за успешный ответ. Поинты списываются, когда метод вернул HTTP 200. Ответы 4xx и 5xx баланс не меняют.
- Скачивание — один раз за файл. Загрузка списывает 10 поинтов (для 1080p — 12) при постановке в очередь. Последующие запросы статуса той же загрузки бесплатны, сколько бы их ни было.
- Общий кэш не удешевляет запрос. Ролик, который лежит у нас, но которого ваш бот ещё не получал, приходит в первом же ответе — а списывается за него полная цена: 10 поинтов, для 1080p — 12. Причина в том, что
file_idв Telegram привязан к конкретному боту, и файл всё равно нужно передать вашему. - Повторная отдача — 2 поинта. Если ваш бот уже получал этот ролик в этом формате, повторный запрос стоит 2 поинта, независимо от качества и озвучки.
- Перед платным запросом проверяется остаток. Если поинтов меньше, чем стоит метод, вы получите 403 и запрос не выполнится. Бесплатные методы работают при любом балансе.
- Статистика доступна из кода.
GET /me/balanceвозвращает остаток,GET /me/stats— списания по дням и типам запросов за последнюю неделю.
Ошибки и что с ними делать
Ошибки приходят в JSON с полем error; у неудавшегося скачивания дополнительно есть status: "failed". Ниже — коды, которые вы встретите на практике.
| Код | Что означает | Что делать |
|---|---|---|
| 400 | Неверный параметр: идентификатор видео не похож на идентификатор YouTube, пустой поисковый запрос, неизвестный kind или формат субтитров. | Исправьте запрос. Повторять без изменений бессмысленно. |
| 401 | Токен отсутствует, отозван, либо при нескольких ботах не передан или не найден X-Bot-Id. | Проверьте заголовки X-Token и X-Bot-Id и статус токена в кабинете. |
| 403 | Недостаточно поинтов для этого запроса. | Пополните баланс. Бесплатные методы продолжают работать. |
| 404 | Видео недоступно: удалено, приватное, только для участников, ограничено по возрасту или региону, ещё не вышло. Причина в поле error. | Покажите пользователю причину из ответа. Повтор не поможет, поинты не списаны. |
| 500 | Скачивание не удалось после всех попыток или временный сбой на нашей стороне. | Повторите через минуту. Если ошибка устойчива — напишите в поддержку с идентификатором видео. |
Не спешите повторять запрос
Не разобрались?
Токен выпускается за минуту
200 поинтов при регистрации — около 20 свежих скачиваний, карта не нужна. Пополнение от 5 $. Вход через Telegram.