Cum obții transcrierea unui video YouTube cu un API (curl, Python, JavaScript)

Ca să obții transcrierea unui video YouTube cu un API, trimiți o cerere HTTP cu URL-ul sau ID-ul videoclipului și o cheie API, apoi citești transcrierea din răspuns. Acest ghid arată cererea în curl, Python și JavaScript cu API-ul de transcrieri sum.video, apoi explică formatele, erorile și costul.

Ce returnează API-ul

Endpoint-ul returnează subtitrările existente ale unui video YouTube public, scrise de autor sau generate automat de YouTube. Nu transcrie audio. Dacă videoclipul nu are subtitrări, primești o eroare, nu o presupunere (mai jos).

Esențialul:

• Endpoint: POST https://sum.video/api/v1/transcript (GET funcționează și el)
• Autentificare: cheia ta în antetul X-API-Key, sau Authorization: Bearer <key>
• Intrare: url sau video_id
• lang opțional (implicit en)
• format opțional: json, text sau srt

Răspunsul spune limba reală a pistei de subtitrări și dacă a fost generată automat, ca să știi ce calitate să te aștepți.

Pasul 1: creează o cheie API

Autentifică-te și creează o cheie în panoul API (/dashboard/api pe sum.video). Poți avea până la 5 chei active, util ca să separi cheia de test de cea de producție. Prima ta cheie vine cu 10 credite gratuite, suficiente pentru 5 transcrieri, deci poți încerca tot ce urmează fără costuri.

Pasul 2: fă prima cerere

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

Fiindcă și GET funcționează, poți testa chiar dintr-un script care doar construiește URL-ul. E mai bine să trimiți cheia în antet, ca să nu ajungă în loguri.

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+ sau browser)

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

Păstrează cheia pe server. O cheie din codul de browser poate fi copiată de oricine deschide instrumentele de dezvoltare.

Pasul 3: alege formatul potrivit

Dacă vrei să faci link către un moment din video, folosește json și construiește linkul din offset-ul segmentului. Pentru un LLM, text e mai scurt și mai simplu. Dacă mai târziu vrei să cauți manual într-o transcriere, vezi cum cauți în transcrierea unui video YouTube.

Pasul 4: alege limba

lang este implicit en. Setează limba dorită, de exemplu de sau es. Răspunsul spune limba pistei returnate de fapt, deci verific-o în loc să o presupui. Adesea un videoclip are o singură pistă de subtitrări, iar API-ul returnează subtitrările reale, deci nu traduce pentru tine.

Pasul 5: tratează erorile

Planifică de la început aceste situații:

• 404 no_transcript: videoclipul nu are subtitrări sau este o transmisiune live, un videoclip privat ori șters. Nu e nimic de reîncercat. Sari peste el sau cere utilizatorului alt videoclip.
• 402 budget_exceeded: ai atins limita lunară de credite pe care ai setat-o. Vezi secțiunea următoare.
• Limita de cereri: fiecare cheie permite 60 de cereri pe minut. Eșalonează lucrul în loturi și încetinește când ești limitat.
• Defecțiuni din partea noastră: reîncearcă după puțin timp. Nu costă nimic.

O buclă simplă care reîncearcă la erori de server și sare la 404 acoperă majoritatea nevoilor de producție.

Cât costă

Fiecare transcriere costă 2 credite. Cererile care nu returnează transcriere sau eșuează din partea sum.video nu costă nimic, deci un 404 nu îți golește niciodată soldul. Soldul îl vezi cu GET /api/v1/credits.

Creditele se vând în pachete unice care nu expiră niciodată:

Abonații Pro primesc în plus 100 de credite bonus pe lună. Pentru sarcini mari, cum ar fi importul unui canal întreg, citește scenariul transcrieri YouTube pentru o aplicație RAG la scară mare, care tratează reîncărcarea automată și bugetele. Vezi și prețurile.

Limite de știut înainte să construiești

• Funcționează doar videoclipurile cu subtitrări. Este cauza principală pentru 404 no_transcript.
• Subtitrările generate automat pot avea greșeli, mai ales la nume, accente și termeni tehnici.
• API-ul returnează doar transcrierea. Nu face rezumate. Dacă vrei rezumat, marcaje de timp și chat despre transcriere, rezumatorul YouTube le face, iar instrumentul de transcriere este varianta fără cod pentru un singur video.
• API-ul oficial YouTube Data nu este un înlocuitor aici. Metoda sa de descărcare a subtitrărilor cere permisiunea de a edita videoclipul, deci este pentru propriile tale videoclipuri (documentația Google).

Surse

• YouTube Data API: Captions.download
• API-ul de transcrieri sum.video