Документация

Введение

Tunelio API предоставляет прямые ссылки на YouTube-видео и аудио, подробные метаданные и транскрипты с таймкодами. Ссылка для скачивания возвращается в том же запросе — без очередей, polling и webhook прогресса.

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

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

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

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

Начало работы

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

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

Authorization: Bearer tnl_8f3a92b1c4d5e6f7a8b9c0d1e2f3a4b5

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

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

Начало работы

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

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

1. Download Streams (/create)

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

2. YouTube Transcripts & Subtitles (/transcript)

Extract full timestamped text, auto vs manual subtitles, SRT, VTT, or plain text without bot detection walls (6 credits).

curl -X GET "https://tunelio.dev/transcript?url=dQw4w9WgXcQ&lang=en&format=json" \
  -H "Authorization: Bearer tnl_…"

Endpoint'ы

GET /info

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

Query параметры

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

Попробовать

GETtunelio.dev/info

Попробовать · стоимость 6 credits

urlstring · обязательный

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 кредитов за вызов.

Endpoint'ы

GET /create

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

Query параметры

urlstringrequiredYouTube URL — те же форматы что и в /info.

qualitystringrequiredОдно из: 144p, 240p, 360p, 480p, 720p, 1080p, 2160p (только Mega), mp3 для аудио или opus для аудио Opus без перекодирования.

audioBitrateintegeroptionalНеобязательно. Используется только при quality=opus — выбирает ближайший нативный битрейт Opus в кбит/с (например, 64). Для остальных значений качества игнорируется.

Попробовать

GETtunelio.dev/create

Попробовать · стоимость 10 credits

urlstring · обязательный

qualitystring · обязательный

GET tunelio.dev/create?url=https://youtu.be/dQw4w9WgXcQ&quality=1080p

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

urlstring (URL)Signed stream 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, mp3, or opus.

modestring"video" or "audio".

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".

statusstring"ok" on success — otherwise the error message.

Стоимость

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

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

Endpoint'ы

GET /transcript

Fetch full transcripts and subtitles for any YouTube video with timestamps, language selection, and manual vs. auto-generated indicators.

Query параметры

urlstringrequiredYouTube watch, shorts, embed, youtu.be URL or 11-char Video ID.

langstringoptionalTarget language code (e.g. en, es, de, ja). Defaults to en.

typestringoptionalFilter by type: any (prefers manual), manual, or auto.

formatstringoptionalOutput format: json (default), text, srt, or vtt.

Попробовать

GETtunelio.dev/transcript

Попробовать · стоимость 6 credits

urlstring · обязательный

langstring

formatstring

GET tunelio.dev/transcript?url=https://youtu.be/dQw4w9WgXcQ&lang=en&format=json

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

video_idstringThe 11-character YouTube video ID.

titlestringTitle of the YouTube video.

languagestringSelected language code.

language_namestringDisplay name of selected language.

is_generatedbooleanTrue if auto-generated ASR, false if manually uploaded.

typestring"manual" or "auto".

available_languagesarray<Language>List of all available subtitle/transcript tracks.

segments_countintegerNumber of timed text segments.

segmentsarray<Segment>Array of { start, duration, text } objects.

full_textstringComplete continuous text of the transcript.

statusstring"ok" on success.

Стоимость

Extracting a transcript costs 6 credits per unique video request. Cached repeats respond in under 5ms.

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 снова для новой.

Стоимость

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

Repackaging

By default /tunnel streams the file as it is built — right for a download, wrong for a player: there is no Range and no length known up front. Add one of these to the same link to get the same media packaged differently. The link does not change, nothing extra is charged, and the result is built once and then cached.

&progressive=1A plain, non-fragmented mp4: moov first, exact Content-Length, full Range and seeking. This is the shape iOS and AVPlayer want.

&start=90&end=100Only that slice, as a progressive mp4. The start snaps back to the nearest keyframe — the same as ffmpeg -ss -c copy — so a clip can begin a few seconds early. The end is exact.

&hls=1An HLS playlist (application/vnd.apple.mpegurl) over the same media, for AVFoundation’s native path. Its entries point back at /tunnel with &hls=data.

Repackaging applies to merged mp4 downloads. Audio-only and other formats answer 400, a clip combined with hls answers 400, and a file too large to build answers 413 — download it normally instead.

Справочник

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

Лимиты применяются к 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