YouTube-Transkript per API abrufen (curl, Python, JavaScript)

Um ein YouTube-Transkript per API abzurufen, schickst du eine HTTP-Anfrage mit der Video-URL oder -ID und einem API-Schlüssel und liest das Transkript aus der Antwort. Diese Anleitung zeigt die Anfrage in curl, Python und JavaScript mit der sum.video Transcript API und behandelt dann Formate, Fehler und Kosten.

Was die API zurückgibt

Der Endpunkt liefert die vorhandenen Untertitel eines öffentlichen YouTube-Videos, entweder vom Urheber geschrieben oder von YouTube automatisch erzeugt. Er transkribiert keine Audiodaten. Hat ein Video keine Untertitel, bekommst du einen Fehler statt einer Vermutung (mehr dazu unten).

Die Grundlagen:

• Endpunkt: POST https://sum.video/api/v1/transcript (GET funktioniert auch)
• Authentifizierung: dein Schlüssel im Header X-API-Key oder Authorization: Bearer <key>
• Eingabe: url oder video_id
• Optional lang (Standard en)
• Optional format: json, text oder srt

Die Antwort nennt außerdem die tatsächliche Sprache der Untertitelspur und ob sie automatisch erzeugt wurde, sodass du die zu erwartende Qualität einschätzen kannst.

Schritt 1: API-Schlüssel erstellen

Melde dich an und erstelle einen Schlüssel im API-Dashboard (/dashboard/api auf sum.video). Du kannst bis zu 5 aktive Schlüssel haben, praktisch, um einen Test- von einem Produktionsschlüssel zu trennen. Dein erster Schlüssel kommt mit 10 kostenlosen Credits, genug für 5 Transkripte, damit du alles Folgende ohne Kosten testen kannst.

Schritt 2: Die erste Anfrage senden

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

Da GET ebenfalls funktioniert, kannst du auch aus einem Skript testen, das nur URLs baut. Gib den Schlüssel lieber im Header an, damit er nicht in Logs landet.

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

Halte den Schlüssel auf einem Server. Ein Schlüssel im Browsercode lässt sich von jedem kopieren, der die Entwicklertools öffnet.

Schritt 3: Das richtige Format wählen

Wenn du auf eine Stelle im Video verlinken willst, nimm json und baue den Link aus dem offset des Segments. Zum Füttern eines LLM ist text kleiner und einfacher. Wenn du später von Hand in einem Transkript suchen willst, lies wie du im Transkript eines YouTube-Videos suchst.

Schritt 4: Eine Sprache wählen

lang ist standardmäßig en. Setze die gewünschte Sprache, zum Beispiel de oder es. Die Antwort nennt die Sprache der tatsächlich gelieferten Spur, prüfe sie also, statt sie anzunehmen. Ein Video hat oft nur eine Untertitelspur, und die API liefert echte Untertitel, sie übersetzt also nicht für dich.

Schritt 5: Fehler behandeln

Plane diese Fälle von Anfang an ein:

• 404 no_transcript: Das Video hat keine Untertitel oder ist ein Livestream, ein privates oder ein entferntes Video. Es gibt nichts zu wiederholen. Überspringe es oder bitte den Nutzer um ein anderes Video.
• 402 budget_exceeded: Du hast das von dir eingestellte monatliche Credit-Limit erreicht. Siehe nächster Abschnitt.
• Ratenlimit: Jeder Schlüssel erlaubt 60 Anfragen pro Minute. Verteile Stapelaufgaben und geh zurück, wenn du gedrosselt wirst.
• Fehler auf unserer Seite: Wiederhole mit kurzer Verzögerung. Sie kosten nichts.

Eine einfache Schleife mit Wiederholung bei Serverfehlern und Überspringen bei 404 deckt die meisten Produktionsfälle ab.

Was es kostet

Jedes Transkript kostet 2 Credits. Anfragen, die kein Transkript liefern oder auf Seiten von sum.video scheitern, kosten nichts, ein 404 leert also nie dein Guthaben. Dein Guthaben siehst du mit GET /api/v1/credits.

Credits werden in einmaligen Paketen verkauft, die nie verfallen:

Pro-Abonnenten bekommen außerdem jeden Monat 100 Bonus-Credits. Für größere Lasten, etwa das Einlesen eines ganzen Kanals, lies das Szenario YouTube-Transkripte für eine RAG-App im großen Maßstab, das automatisches Aufladen und Budgets behandelt. Siehe auch die Preise.

Grenzen, die du vor dem Bauen kennen solltest

• Nur Videos mit Untertiteln funktionieren. Das ist der Hauptgrund für 404 no_transcript.
• Automatisch erzeugte Untertitel können Fehler enthalten, besonders bei Namen, Akzenten und Fachbegriffen.
• Die API liefert nur das Transkript. Sie fasst nicht zusammen. Wenn du Zusammenfassungen, Zeitstempel und Chat auf einem Transkript willst, übernimmt das der YouTube-Zusammenfasser, und das Transkript-Tool ist die Variante ohne Code für ein einzelnes Video.
• Die offizielle YouTube Data API ist hier kein Ersatz. Ihre Methode zum Herunterladen von Untertiteln verlangt die Berechtigung, das Video zu bearbeiten, und ist daher für deine eigenen Videos gedacht (Google-Dokumentation).

Quellen

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