К содержанию
200 поинтов при регистрацииБез карты

От токена до первого файла

Это не полная документация, а короткий путь к работающей интеграции: получить токен, сделать первый запрос, скачать видео и отправить его пользователю. Остальные методы — в таблице ниже.

1. Получите токен

Всё делается в кабинете, без переписки с поддержкой.

  1. Шаг 1

    Войдите через Telegram

    Нажмите «Войти» и подтвердите вход в Telegram. Пароля нет; аккаунт создаётся при первом входе, и на нём уже лежат 200 пробных поинтов.

  2. Шаг 2

    Добавьте бота

    Укажите @username бота, которому будут доставляться файлы. Токен BotFather не нужен. Пока бот не подтверждён, запросы от его имени не выполняются — обычно это занимает меньше минуты.

  3. Шаг 3

    Выпустите токен API

    Токен показывается целиком один раз, при создании. Сохраните его в секретах приложения; в кабинете потом видна только маскированная форма. Скомпрометированный токен можно отозвать и выпустить новый.

Токен — это доступ к балансу

Не публикуйте его в клиентском коде, репозиториях и логах. Все запросы к API должны идти с вашего сервера.

2. Авторизация

Токен передаётся в заголовке X-Token с каждым запросом. Базовый адрес API — https://api.massbots.xyz.

Проверка баланса — самый простой первый запрос

bash
curl -H "X-Token: $MASSBOTS_TOKEN" \
  "https://api.massbots.xyz/me/balance"
json
{
  "balance": 4980,
  "bot_name": "my_downloader_bot",
  "bot_id": 123456789,
  "customer_id": 42
}

Несколько ботов на одном аккаунте

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

bash
curl -H "X-Token: $MASSBOTS_TOKEN" \
     -H "X-Bot-Id: 123456789" \
  "https://api.massbots.xyz/me/balance"

3. Примеры запросов

Все методы — GET. Идентификатор видео — тот же, что в адресе YouTube после v=.

Данные о видео

1 поинт. Удобно для карточки перед скачиванием: название, длительность, канал.

bash
curl -H "X-Token: $MASSBOTS_TOKEN" \
  "https://api.massbots.xyz/video/dQw4w9WgXcQ"

Ответ (сокращённо)

json
{
  "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 перечисляет дорожки озвучки, если у ролика их несколько.

bash
curl -H "X-Token: $MASSBOTS_TOKEN" \
  "https://api.massbots.xyz/video/dQw4w9WgXcQ/formats"
json
{
  "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 — это про скорость, а не про цену

Флаг считается по общему кэшу, без привязки к боту: он значит «файл есть у нас», а не «вам он обойдётся дешевле». Ваш бот мог никогда его не получать — тогда запрос спишет полную цену, 10 поинтов или 12 за 1080p, даже при cached: true. Льготные 2 поинта списываются только за повторную отдачу ролика, который ваш бот уже получал. Планировать расход по этому флагу нельзя; фактические списания видны в статистике и в кабинете.

Скачивание асинхронное. Один и тот же запрос запускает загрузку и возвращает её статус: queued — задача в очереди, downloading — в работе, ready — готово, в ответе есть file_id. Повторяйте запрос раз в пять-семь секунд: при более частом опросе API вернёт downloading с подсказкой о рекомендуемой паузе в поле message. Если файл был в общем кэше, readyприходит сразу.

bash
# Первый вызов ставит задачу в очередь…
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.

python
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 результатов. Ответ — массив тех же объектов, что возвращает метод данных о видео или канале.

bash
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 — с таймкодами.

bash
# Список дорожек (бесплатно)
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 или en102 за повторную отдачу, 12 за 1080p
GET /video/{id}/subtitlesСписок доступных дорожек субтитров.——
GET /video/{id}/subtitles/{lang}Текст субтитров на выбранном языке.f — формат: txt (по умолчанию) или srt1
GET /searchПоиск по YouTube, до 25 результатов.q — запрос; kind — video (по умолчанию) или channel5
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Скачивание не удалось после всех попыток или временный сбой на нашей стороне.Повторите через минуту. Если ошибка устойчива — напишите в поддержку с идентификатором видео.

Не спешите повторять запрос

Прежде чем вернуть ошибку, мы сами пробуем довести загрузку до конца. Немедленный повтор с вашей стороны обычно упирается в ту же причину — подождите минуту.

Не разобрались?

Напишите в поддержку с идентификатором видео и временем запроса: @MassbotsDevTeamBot. Частые вопросы собраны на отдельной странице.

Токен выпускается за минуту

200 поинтов при регистрации — около 20 свежих скачиваний, карта не нужна. Пополнение от 5 $. Вход через Telegram.