Jak pobrać transkrypcję z YouTube przez API (curl, Python, JavaScript)

Aby pobrać transkrypcję z YouTube przez API, wyślij jedno zapytanie HTTP z adresem URL lub identyfikatorem filmu i kluczem API, a transkrypcję odczytaj z odpowiedzi. Ten poradnik pokazuje zapytanie w curl, Pythonie i JavaScripcie z użyciem API transkrypcji sum.video, a potem omawia formaty, błędy i koszty.

Co zwraca API

Endpoint zwraca istniejące napisy publicznego filmu z YouTube, napisane przez autora albo wygenerowane automatycznie przez YouTube. Nie zamienia dźwięku na tekst. Jeśli film nie ma napisów, dostajesz błąd zamiast zgadywania (więcej niżej).

Podstawy:

• Endpoint: POST https://sum.video/api/v1/transcript (GET też działa)
• Uwierzytelnianie: twój klucz w nagłówku X-API-Key albo Authorization: Bearer <key>
• Dane wejściowe: url lub video_id
• Opcjonalnie lang (domyślnie en)
• Opcjonalnie format: json, text lub srt

Odpowiedź podaje też prawdziwy język ścieżki napisów i informację, czy została wygenerowana automatycznie, więc wiesz, jakiej jakości się spodziewać.

Krok 1: Utwórz klucz API

Zaloguj się i utwórz klucz w panelu API (/dashboard/api w sum.video). Możesz mieć do 5 aktywnych kluczy, co przydaje się do oddzielenia klucza testowego od produkcyjnego. Pierwszy klucz dostaje 10 darmowych kredytów, czyli tyle, ile na 5 transkrypcji, więc wszystko poniżej możesz przetestować bez kosztów.

Krok 2: Wyślij pierwsze zapytanie

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"}'

Ponieważ GET też działa, możesz testować ze skryptu, który tylko buduje adresy URL. Klucz lepiej podawać w nagłówku, żeby nie trafił do logów.

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+ lub przeglądarka)

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());
}

Trzymaj klucz na serwerze. Klucz umieszczony w kodzie przeglądarki może skopiować każdy, kto otworzy narzędzia deweloperskie.

Krok 3: Wybierz odpowiedni format

Jeśli chcesz linkować do momentu w filmie, użyj json i zbuduj link z offset segmentu. Do karmienia modelu językowego text jest mniejszy i prostszy. Jeśli później chcesz ręcznie przeszukiwać transkrypcję, zobacz jak szukać w transkrypcji filmu z YouTube.

Krok 4: Wybierz język

lang domyślnie ma wartość en. Ustaw język, który chcesz, na przykład de lub es. Odpowiedź podaje język ścieżki, która faktycznie została zwrócona, więc sprawdzaj go zamiast zakładać. Film często ma tylko jedną ścieżkę napisów, a API zwraca prawdziwe napisy, więc nie tłumaczy ich za ciebie.

Krok 5: Obsłuż błędy

Zaplanuj te przypadki od pierwszego dnia:

• 404 no_transcript: film nie ma napisów albo jest transmisją na żywo, filmem prywatnym lub usuniętym. Nie ma czego ponawiać. Pomiń go albo poproś użytkownika o inny film.
• 402 budget_exceeded: osiągnięto skonfigurowany miesięczny limit kredytów. Zobacz następną sekcję.
• Limit zapytań: każdy klucz pozwala na 60 zapytań na minutę. Rozłóż zadania wsadowe w czasie i zwalniaj, gdy zostaniesz ograniczony.
• Błędy po naszej stronie: ponów z krótkim opóźnieniem. Nic nie kosztują.

Prosta pętla z ponawianiem przy błędach serwera i pomijaniem przy 404 pokrywa większość potrzeb produkcyjnych.

Ile to kosztuje

Każda transkrypcja kosztuje 2 kredyty. Zapytania, które nie zwracają transkrypcji albo kończą się błędem po stronie sum.video, nic nie kosztują, więc 404 nigdy nie uszczupla salda. Saldo sprawdzisz przez GET /api/v1/credits.

Kredyty sprzedajemy w jednorazowych pakietach, które nigdy nie wygasają:

Subskrybenci Pro dostają też 100 bonusowych kredytów miesięcznie. Przy większym obciążeniu, na przykład wczytywaniu całego kanału, przeczytaj scenariusz transkrypcje z YouTube dla aplikacji RAG na dużą skalę, który omawia automatyczne doładowanie i budżety. Zobacz też cennik.

Ograniczenia, które warto znać przed budową

• Działają tylko filmy z napisami. To główny powód 404 no_transcript.
• Napisy generowane automatycznie mogą zawierać błędy, szczególnie w nazwach, akcentach i terminach technicznych.
• API zwraca tylko transkrypcję. Nie streszcza. Jeśli chcesz streszczeń, znaczników czasu i czatu na wierzchu transkrypcji, robi to streszczanie YouTube, a narzędzie do transkrypcji to wersja bez kodowania dla jednego filmu.
• Oficjalne YouTube Data API nie jest tu zamiennikiem. Jego metoda pobierania napisów wymaga uprawnień do edycji filmu, więc jest przeznaczona dla twoich własnych filmów (dokumentacja Google).

Źródła

• YouTube Data API: Captions.download
• API transkrypcji sum.video