Як отримати транскрипцію YouTube за допомогою API (curl, Python, JavaScript)

Щоб отримати транскрипцію YouTube за допомогою API, надішли HTTP-запит з URL або ID відео та 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