Перейти к содержимому
Документация

Введение

Tunelio API возвращает прямую ссылку для скачивания любого YouTube видео или аудио в одном запросе — без очередей, опроса или webhook прогресса. Весь API — это два endpoint: GET /info для метаданных, GET /create для ссылки на скачивание.

Базовый URL: https://tunelio.dev. Все запросы по TLS 1.2+. Ответы — JSON в кодировке UTF-8.

Модель работы

Вызовите /info, чтобы узнать доступные форматы для URL, затем вызовите /create с выбранным качеством. Ответ /create содержит url — ссылку на наш CDN tunnel. Передайте её пользователю, загрузчику или предподписанной S3 загрузке. Третьего шага нет.

Никакого опроса. Если вы использовали другие download API, вы привыкли к job ID и SSE потокам. У нас этого нет — каждый запрос завершается одним ответом.
Начало работы

Аутентификация

Все запросы требуют API ключ, отправленный как Bearer токен в заголовке Authorization.

Authorization: Bearer tnl_8f3a92b1c4d5e6f7a8b9c0d1e2f3a4b5

Сначала войдите через Telegram (одним нажатием в @TunelioDevBot — без email и пароля), затем создайте API-ключ в Панели управления. Весь процесс занимает около 60 секунд и не требует способа оплаты.

Храните ключ на стороне сервера. Любой, у кого есть ключ, может тратить ваши кредиты. Никогда не размещайте его в клиентском бандле или мобильном приложении — проксируйте через свой backend.
Начало работы

Быстрый старт

Сделайте первый вызов в три строки. Замените ключ на свой, а URL — на любую YouTube ссылку.

curl "https://tunelio.dev/create?quality=720p&url=https://youtu.be/dQw4w9WgXcQ" \
  -H "Authorization: Bearer tnl_…"
Endpoint'ы

GET /info

Разрешает YouTube URL и возвращает полные метаданные — заголовок, длительность, миниатюру и каждый доступный видео и аудио формат с размерами файлов и разрешением.

Query параметры

urlstringrequiredYouTube URL: watch?v=, youtu.be/, /shorts/, /embed/ или /live/. Все эти варианты обрабатываются одинаково.

Попробовать

GETtunelio.dev/info
Попробовать · стоимость 6 credits
GET tunelio.dev/info?url=https://youtu.be/dQw4w9WgXcQ

Формат ответа

titlestringVideo title as published.
duration_secondsintegerTotal length in seconds.
duration_strstringHuman-readable HH:MM:SS (or MM:SS when < 1h). Zero-padded.
thumbnailstring (URL)Highest-resolution thumbnail available.
formats[]array<Format>Every video format. See sub-fields below.
formats[].qualitystringHuman label: 144p, 240p, 360p, 480p, 720p, 1080p.
formats[].file_sizeinteger (bytes)Exact size in bytes.
formats[].file_size_strstringHuman-readable size — e.g. "84.50 MB" or "1.20 GB".
formats[].widthintegerEncoded frame width in pixels.
formats[].heightintegerEncoded frame height in pixels.
audioFormatobject<Audio>|nullThe best MP3 audio rendition — single object, or null if no audio track is available.
audioFormat.formatstringContainer — currently mp3.
audioFormat.file_sizeintegerExact MP3 size in bytes.
audioFormat.file_size_strstringHuman-readable MP3 size — e.g. "35.01 MB".

Стоимость

6 кредитов за вызов. Идентичные URL возвращаются бесплатно в течение 30 минут (кэш).

Endpoint'ы

GET /create

Создаёт прямую подписанную CDN ссылку для выбранного формата. Ссылка возвращается в том же ответе — нет задачи для опроса, нет webhook для прослушивания.

Query параметры

urlstringrequiredYouTube URL — те же форматы что и в /info.
qualitystringrequiredОдно из: 144p, 240p, 360p, 480p, 720p, 1080p, 2160p (только Mega), или mp3 для аудио.

Попробовать

GETtunelio.dev/create
Попробовать · стоимость 10 credits
GET tunelio.dev/create?url=https://youtu.be/dQw4w9WgXcQ&quality=1080p

Формат ответа

urlstring (URL)Signed CDN tunnel URL. Hand to your user or pipe to storage.
filenamestringSuggested filename based on the video title and chosen format.
qualitystringEcho of your requested quality — e.g. 1080p or mp3.
modestring"video" or "audio".
typestring"merge" (video+audio muxed) or "single" (audio-only or pre-muxed).
expiresinteger (unix)Timestamp when the signed URL stops working — typically 6 hours out.
file_sizeintegerFinal file size in bytes.
file_size_strstringHuman-readable size — e.g. "84.50 MB".
statusstringAlways "tunnel" on success.

Стоимость

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

Байты не проходят через ваш сервер. Backend видит только небольшой JSON ответ. Tunnel URL стримит напрямую с нашего CDN к конечному пользователю.
Endpoint'ы

GET /credits

Возвращает остаток кредитов и текущий тариф. Используйте, чтобы проверить остаток перед серией вызовов или показать баланс в собственной панели.

Без query параметров — только ваш API ключ. Тот же Bearer токен (или заголовок X-API-Key), что и везде, авторизует этот вызов.

Попробовать

GETtunelio.dev/credits
Попробовать · стоимость бесплатно
GET tunelio.dev/credits

Формат ответа

creditsintegerОстаток кредитов, целое число.
planstringВаш текущий тариф: trial, pro, ultra или mega. Истёкший платный тариф возвращается как trial.

Заголовки ответа

Тот же баланс дублируется в заголовках ответа, как у /info и /create — удобно, если нужны числа без разбора тела ответа:

X-Credits-RemainingintОстаток кредитов.
X-Credits-PlanstrНазвание текущего тарифа.

Стоимость

Бесплатно. Проверка баланса никогда не тратит кредиты.

Этот endpoint только для чтения и всегда бесплатен, поэтому опрашивать его можно сколько угодно — например, перед большой серией — ничего не расходуя.
Endpoint'ы

/tunnel

/tunnel — это URL, который возвращает /create. Вы не вызываете его из кода — вы передаёте URL вашему пользователю, тегу <a download>, S3 загрузчику, Telegram боту и т.д.

Что возвращает

Сам файл — MP4 или MP3 — с соответствующими заголовками Content-Type и Content-Disposition: attachment; filename="…". Поддерживает HTTP range запросы, поэтому видео плееры могут перематывать, а загрузчики — возобновлять.

Аутентификация

Не требуется. URL самоподписан с временной меткой exp и HMAC sig. После expires ссылка возвращает 410 Gone — вызовите /create снова для новой.

Стоимость

Бесплатно. Трафик за наш счёт в разумных пределах — мы ограничиваем злоупотребление, но обычное использование никогда не натыкается на лимиты.

Справочник

Лимиты запросов

Лимиты применяются к API ключу, измеряются в запросах в минуту. Сбрасываются каждые 60 секунд по скользящему окну. На тарифах Ultra и Mega лимитов нет.

Trial15 req / min
Pro5 req / sec
Ultrano limit
Megano limit

При превышении возвращается 429 Too Many Requests с заголовком Retry-After (в секундах). Если регулярно упираетесь в потолок — обновите тариф, а не добавляйте backoff на стороне клиента. Лимиты существуют, чтобы вы случайно не израсходовали все кредиты.

Справочник

Ошибки

Все ошибки имеют одинаковую структуру:

{
  "error": "invalid_url",
  "message": "Provided URL is not a recognised YouTube link."
}

Коды статусов

400invalid_requestMissing or malformed parameter — usually a bad URL or unknown quality.
401unauthorizedMissing or invalid Bearer token.
402insufficient_creditsYour account is out of credits. Top up or upgrade.
404not_foundVideo does not exist, is private, or was deleted.
410goneYou called a /tunnel URL after its expires timestamp.
429rate_limitedPlan rate limit hit. Respect the Retry-After header.
500server_errorUnexpected on our side. Safe to retry with exponential backoff.
503upstream_changedYouTube changed something we hadn't patched yet. Usually self-heals within an hour.
Справочник

Кредиты и оплата

Каждый вызов стоит фиксированное количество кредитов независимо от размера или длительности видео:

GET /info6 credits
GET /create10 credits
/tunnel downloadfree

Типичная связка "получить info, затем скачать" — 16 кредитов. Новые аккаунты получают 100 бесплатных кредитов. Платные тарифы продлеваются ежемесячно, каждый цикл начинается со свежими кредитами.

Неудачные запросы (4xx и 5xx) не тратят кредиты — вы платите только за успешно обработанные запросы.

Что-то непонятно или не хватает?
Напишите нам в Telegram → @TunelioDevBot