Перейти к содержимому

YouTube Transcript API

Отправьте ссылку на YouTube и получите транскрипт в том же запросе: сегменты с таймкодами в JSON или готовые SRT, VTT и обычный текст. Ручные субтитры, когда они есть, автоматические — когда нет, плюс полный список языков, чтобы вы всегда знали, что именно получили.

Что делает transcript API

YouTube transcript API превращает ссылку на видео в его субтитры в виде структурированных данных. Endpoint GET /transcript у Tunelio находит видео, выбирает лучшую дорожку субтитров для запрошенного языка (предпочитая ручные субтитры автоматическим) и возвращает каждый сегмент с временем начала и длительностью — плюс склеенный полный текст и каталог всех остальных языков видео. Без автоматизации браузера, без cookies, без yt-dlp, который нужно обновлять: один HTTPS-запрос с вашим API-ключом.

Как это работает

1. Вызовите /transcript со ссылкой
Любая ссылка watch, shorts, embed или youtu.be — либо просто ID видео. Добавьте lang (по умолчанию en), type (any, manual или auto) и format (json, text, srt или vtt).
2. Мы получаем субтитры на своей стороне
Tunelio забирает дорожки субтитров у YouTube собственным парком извлечения, поэтому бот-проверки, репутация IP и смена форматов никогда не доходят до вашего кода.
3. Используйте ответ напрямую
JSON идёт прямо в приложение или LLM-пайплайн; SRT и VTT — в видеоплеер; текст — в поисковый индекс и саммари. Типичная задержка — около секунды.

Готовые примеры

Замените tnl_… на ваш API-ключ из Dashboard. Тот же ключ работает для /info и /create.

cURL
curl -X GET "https://tunelio.dev/transcript?url=dQw4w9WgXcQ&lang=en&format=json" \
  -H "Authorization: Bearer tnl_…"
Node.js
const res = await fetch(
  "https://tunelio.dev/transcript?" + new URLSearchParams({
    url: "dQw4w9WgXcQ",
    lang: "en",
    format: "json",
  }),
  { headers: { Authorization: "Bearer " + process.env.TUNELIO_KEY } }
);
const data = await res.json();
console.log(data.full_text);
console.log(data.segments); // [{ start: 1.36, duration: 1.68, text: "..." }]
Python
import os, requests

res = requests.get(
    "https://tunelio.dev/transcript",
    params={"url": "dQw4w9WgXcQ", "lang": "en", "format": "json"},
    headers={"Authorization": f"Bearer {os.environ['TUNELIO_KEY']}"}
)
data = res.json()
print("Title:", data["title"])
print("Full text:", data["full_text"])
for seg in data["segments"]:
    print(f"[{seg['start']}s -> +{seg['duration']}s] {seg['text']}")
Что приходит в ответ
{
  "video_id": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up",
  "language": "en",
  "language_name": "English",
  "is_generated": false,
  "type": "manual",
  "available_languages": [
    { "code": "en", "name": "English", "is_generated": false, "type": "manual" },
    { "code": "es", "name": "Spanish", "is_generated": true,  "type": "auto" }
  ],
  "segments_count": 61,
  "segments": [
    { "start": 18.64, "duration": 3.24, "text": "We're no strangers to love" },
    { "start": 21.88, "duration": 2.60, "text": "You know the rules and so do I" }
  ],
  "full_text": "We're no strangers to love You know the rules and so do I …",
  "status": "ok"
}

JSON-ответ содержит ID и название видео, фактически отданный язык (language, language_name), признак автогенерации (is_generated, type), список available_languages, segments_count, массив segments и full_text. Видео без субтитров возвращает 404, и запрос не тарифицируется — неудачные запросы возвращаются на баланс автоматически.

Форматы вывода

json (по умолчанию)
Структурированные сегменты со start, duration и text, плюс full_text и каталог языков — для приложений, RAG-пайплайнов и анализа.
text
Весь транскрипт обычным текстом (text/plain) — для саммари, поисковой индексации и промптов LLM.
srt
Субтитры SubRip (text/srt) — для плееров, редакторов и инструментов вшивания.
vtt
WebVTT (text/vtt) — для HTML5 <track> и веб-плееров.

Параметры

url
Ссылка YouTube watch, shorts, embed или youtu.be, либо 11-символьный ID видео. Обязателен.
lang
Код языка: en, es, de, hi, zh и т. д. По умолчанию en. При type=any Tunelio откатывается на английский, затем на первую доступную дорожку, и сообщает, какую использовал.
type
any (предпочесть ручные субтитры, откат на автоматические), manual (только ручные) или auto (только автоматические). По умолчанию any.
format
json, text, srt или vtt. По умолчанию json.

Что на этом строят разработчики

LLM- и RAG-пайплайны
Передавайте модели сегменты с таймкодами, сохраняйте время начала у каждого чанка и привязывайте ответы к точной секунде видео.
Субтитры и доступность
Отдавайте SRT или VTT своему плееру, переводите субтитры или публикуйте транскрипты рядом со встроенным видео.
Поиск и саммари
Индексируйте полный текст, чтобы искать внутри видео; генерируйте саммари, главы и хайлайты.
Боты и автоматизации
Telegram- или Discord-боты, отвечающие «что сказали на 12:30?», сценарии в стиле Zapier, модерация контента.

Цены

Запрос транскрипта стоит 6 кредитов — как /info. Новые аккаунты получают 100 бесплатных кредитов (шестнадцать транскриптов) без карты. Платные тарифы начинаются от $9 в месяц за 100 000 кредитов.

В сравнении с youtube-transcript-api или yt-dlp у себя

Открытые библиотеки вроде youtube-transcript-api и yt-dlp хорошо забирают субтитры с ноутбука. На сервере они наследуют бот-проверки YouTube: IP дата-центров получают проверки или блокировки, видео с возрастным ограничением требуют cookies, а каждое изменение YouTube означает обновление библиотеки и редеплой. Это реальные расходы, когда транскрипты — функция продукта, а не разовый скрипт.

Tunelio переносит эту работу на свою сторону. У вас остаётся один HTTPS-вызов и JSON-контракт, который не меняется вместе с YouTube. Если транскрипт нужен изредка и с собственной машины — бесплатные библиотеки подходят; если транскрипты в продукте — API дешевле, чем сопровождение.

Частые вопросы

Работает ли с видео без ручных субтитров?

Да. При type=any (по умолчанию) Tunelio возвращает автоматические субтитры YouTube, если ручной дорожки нет, и помечает ответ is_generated: true.

Какие языки поддерживаются?

Все языки, которые есть у самого видео — ручные и автоматические дорожки. Укажите код через lang; ответ перечисляет все available_languages, чтобы вы могли сделать выбор языка.

Насколько точны таймкоды?

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

Что будет, если у видео нет субтитров?

API вернёт 404 с понятным сообщением, а кредиты за этот запрос вернутся автоматически. Приватные и недоступные видео тоже дают 404.

Есть ли лимит запросов?

У Trial и Pro есть лимит запросов в минуту, описанный на странице тарифов; у Ultra и Mega частота запросов не ограничена. Вы платите кредитами, а не запросами.

Открыть документацию API