Как получить транскрипт YouTube через API (curl, Python, JavaScript)

Чтобы получить транскрипт YouTube через API, отправь один HTTP-запрос с URL или идентификатором видео и ключом API, а транскрипт прочитай из ответа. В этом руководстве запрос показан на curl, Python и JavaScript с помощью API транскриптов sum.video, а затем разобраны форматы, ошибки и стоимость.

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

Эндпоинт возвращает существующие субтитры публичного видео YouTube: написанные автором или сгенерированные YouTube автоматически. Он не расшифровывает аудио. Если у видео нет субтитров, ты получишь ошибку, а не догадку (подробнее ниже).

Основы:

• Эндпоинт: POST https://sum.video/api/v1/transcript (GET тоже работает)
• Аутентификация: твой ключ в заголовке X-API-Key или Authorization: Bearer <key>
• Вход: url или video_id
• Необязательный lang (по умолчанию en)
• Необязательный format: json, text или srt

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

Шаг 1: Создай ключ API

Войди и создай ключ на панели API (/dashboard/api на sum.video). Можно иметь до 5 активных ключей, это удобно, чтобы разделить тестовый и рабочий ключи. К первому ключу прилагается 10 бесплатных кредитов, этого хватает на 5 транскриптов, так что всё ниже можно проверить бесплатно.

Шаг 2: Отправь первый запрос

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

Поскольку GET тоже работает, можно тестировать из скрипта, который лишь собирает URL. Ключ лучше передавать в заголовке, чтобы он не попал в логи.

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript (Node 18+ или браузер)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

Храни ключ на сервере. Ключ в коде для браузера может скопировать любой, кто откроет инструменты разработчика.

Шаг 3: Выбери подходящий формат

Если планируешь ссылаться на момент видео, используй json и строй ссылку по offset сегмента. Для подачи в LLM text меньше и проще. Если позже захочешь вручную искать по транскрипту, смотри как искать по транскрипту видео YouTube.

Шаг 4: Выбери язык

lang по умолчанию равен en. Укажи нужный язык, например de или es. В ответе сообщается язык дорожки, которая действительно вернулась, поэтому проверяй его, а не предполагай. У видео часто всего одна дорожка субтитров, а API возвращает настоящие субтитры, то есть сам их не переводит.

Шаг 5: Обработай ошибки

Заложи эти случаи с первого дня:

• 404 no_transcript: у видео нет субтитров, либо это прямая трансляция, приватное или удалённое видео. Повторять нечего. Пропусти его или попроси пользователя прислать другое видео.
• 402 budget_exceeded: ты достиг заданного месячного лимита кредитов. См. следующий раздел.
• Лимит запросов: каждый ключ допускает 60 запросов в минуту. Растягивай пакетные задания по времени и притормаживай, когда тебя ограничивают.
• Сбои на нашей стороне: повтори с небольшой задержкой. Они ничего не стоят.

Простой цикл с повтором при ошибках сервера и пропуском при 404 закрывает большинство производственных нужд.

Сколько это стоит

Каждый транскрипт стоит 2 кредита. Запросы, которые не вернули транскрипт или завершились сбоем на стороне sum.video, ничего не стоят, так что 404 никогда не расходует баланс. Баланс можно посмотреть через GET /api/v1/credits.

Кредиты продаются разовыми пакетами, которые не сгорают:

Подписчики Pro также получают 100 бонусных кредитов каждый месяц. Для более тяжёлой нагрузки, например загрузки целого канала, прочитай сценарий транскрипты YouTube для RAG-приложения в большом масштабе, где разбираются автопополнение и бюджеты. См. также цены.

Ограничения, о которых стоит знать до разработки

• Работают только видео с субтитрами. Это главная причина 404 no_transcript.
• В автоматически сгенерированных субтитрах бывают ошибки, особенно в именах, акцентах и технических терминах.
• API возвращает только транскрипт. Он не делает пересказ. Если нужны пересказы, таймкоды и чат поверх транскрипта, это делает суммаризатор YouTube, а инструмент транскриптов это версия без кода для одного видео.
• Официальный YouTube Data API здесь не замена. Его метод скачивания субтитров требует права на редактирование видео, поэтому он подходит для твоих собственных видео (документация Google).

Источники

• YouTube Data API: Captions.download
• API транскриптов sum.video