YouTube-átirat lekérése API-val (curl, Python, JavaScript)

YouTube-átirat API-val való lekéréséhez küldj egyetlen HTTP-kérést a videó URL-jével vagy azonosítójával és egy API-kulccsal, az átiratot pedig olvasd ki a válaszból. Ez az útmutató a kérést curl, Python és JavaScript nyelven mutatja be a sum.video Transcript API segítségével, majd kitér a formátumokra, a hibákra és a költségekre.

Mit ad vissza az API

A végpont egy nyilvános YouTube-videó meglévő feliratait adja vissza, akár a készítő írta őket, akár a YouTube generálta automatikusan. Hangot nem ír át szöveggé. Ha a videónak nincs felirata, találgatás helyett hibát kapsz (erről lentebb).

Az alapok:

• Végpont: POST https://sum.video/api/v1/transcript (a GET is működik)
• Hitelesítés: a kulcsod az X-API-Key fejlécben, vagy Authorization: Bearer <key>
• Bemenet: url vagy video_id
• Opcionális lang (alapértelmezés: en)
• Opcionális format: json, text vagy srt

A válasz azt is megmondja, mi a feliratsáv valódi nyelve, és hogy automatikusan generált-e, így tudod, milyen minőségre számíthatsz.

1. lépés: API-kulcs létrehozása

Jelentkezz be, és hozz létre egy kulcsot az API-irányítópulton (/dashboard/api a sum.video oldalán). Legfeljebb 5 aktív kulcsod lehet, ami jól jön, ha külön akarod választani a tesztelési és az éles kulcsot. Az első kulcsodhoz 10 ingyenes kredit jár, ez 5 átirathoz elég, így az alábbiakat költség nélkül kipróbálhatod.

2. lépés: Az első kérés

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

Mivel a GET is működik, olyan szkriptből is tesztelhetsz, amely csak URL-eket állít össze. A kulcsot inkább a fejlécben add meg, hogy ne kerüljön be a naplókba.

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+ vagy böngésző)

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

A kulcsot tartsd szerveren. A böngészős kódba tett kulcsot bárki kimásolhatja a fejlesztői eszközök megnyitásával.

3. lépés: Válaszd ki a megfelelő formátumot

Ha vissza akarsz linkelni a videó egy pillanatára, használd a json formátumot, és a link a szegmens offset értékéből épül. LLM-be táplálásra a text kisebb és egyszerűbb. Ha később kézzel akarsz keresni egy átiraton belül, olvasd el: hogyan keress egy YouTube-videó átiratában.

4. lépés: Válassz nyelvet

A lang alapértelmezése en. Állítsd arra a nyelvre, amelyet szeretnél, például de vagy es. A válasz jelzi, melyik sáv nyelvét adta vissza valójában, ezért ellenőrizd, ne feltételezd. A videónak gyakran csak egy feliratsávja van, az API pedig valódi feliratokat ad vissza, tehát nem fordít helyetted.

5. lépés: Hibakezelés

Ezekre az esetekre az első naptól készülj fel:

• 404 no_transcript: a videónak nincs felirata, vagy élő közvetítés, privát vagy eltávolított videó. Nincs mit újra próbálni. Hagyd ki, vagy kérj a felhasználótól másik videót.
• 402 budget_exceeded: elérted a beállított havi kreditkeretet. Lásd a következő szakaszt.
• Sebességkorlát: kulcsonként percenként 60 kérés engedélyezett. A tömeges feladatokat oszd el időben, és lassíts, ha korlátoznak.
• A mi oldalunkon fellépő hibák: próbáld újra rövid késleltetéssel. Ezek nem kerülnek semmibe.

Egy egyszerű ciklus, amely szerverhibánál újrapróbál, 404 esetén pedig kihagyja a videót, a legtöbb éles igényt lefedi.

Mennyibe kerül

Egy átirat 2 kreditbe kerül. Azok a kérések, amelyek nem adnak vissza átiratot, vagy a sum.video oldalán hibával végződnek, nem kerülnek semmibe, így egy 404 sosem fogyasztja az egyenleged. Az egyenleget a GET /api/v1/credits hívással nézheted meg.

A krediteket egyszeri csomagokban árusítjuk, és nem járnak le:

A Pro-előfizetők havonta 100 bónusz kreditet is kapnak. Nagyobb munkához, például egy egész csatorna beolvasásához olvasd el a YouTube-átiratok RAG-alkalmazáshoz nagy léptékben forgatókönyvet, amely az automatikus feltöltést és a kereteket is tárgyalja. Lásd még az árakat.

Korlátok, amiket építés előtt ismerned kell

• Csak a feliratos videók működnek. Ez a 404 no_transcript fő oka.
• Az automatikusan generált feliratokban lehetnek hibák, főleg nevekben, akcentusokban és szakkifejezésekben.
• Az API csak az átiratot adja vissza, nem foglal össze. Ha összefoglalókat, időbélyegeket és csevegést szeretnél az átirat fölé, azt a YouTube-összefoglaló tudja, az átiratkészítő eszköz pedig a kódolás nélküli változat egyetlen videóhoz.
• A hivatalos YouTube Data API itt nem helyettesíti ezt. A feliratletöltési metódusa a videó szerkesztési jogosultságát igényli, ezért a saját videóidhoz való (Google-dokumentáció).

Források

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