YouTubeTranskripteAPI-Leitfaden

YouTube-Transkripte per API in großem Umfang herunterladen

Eine praxisnahe Anleitung, um verfügbaren YouTube-Transkripttext im Bulk abzurufen, Sprachen und fehlende Untertitel zu behandeln und die Ergebnisse für Suche, Zusammenfassung oder RAG aufzubereiten.

SocQAktualisiert am 19. Juli 202610 Min. Lesezeit

Ein einzelnes YouTube-Transkript von Hand herunterzuladen ist einfach. Einen verlässlichen Workflow für Hunderte oder Tausende öffentlicher Videos aufzubauen, ist ein anderes Problem: Videos haben möglicherweise keine Untertitel, die gewünschte Sprache ist unter Umständen nicht verfügbar, automatisch erzeugter Text kann Fehler enthalten, und jedes Ergebnis muss mit seiner Quelle verbunden bleiben.

Diese Anleitung zeigt, wie Sie mit der SocQ YouTube Transcripts API verfügbaren öffentlichen YouTube-Transkripttext abrufen, mehrere Video-URLs über eine asynchrone Aufgabe verarbeiten und die normalisierten Ergebnisse für Suche, Zusammenfassung, Recherche oder Retrieval-Augmented Generation aufbereiten.

Kurzantwort: Senden Sie öffentliche YouTube-Video-URLs und optional eine BCP-47-Sprache per POST /v1/youtube/transcripts. Speichern Sie die zurückgegebene task_id, fragen Sie den Aufgaben-Endpunkt ab und lesen Sie die fertigen Datensätze aus data.results.items. SocQ liefert reinen Transkripttext und Videokontext, sofern brauchbare öffentliche Untertitel vorhanden sind. Fehlen Untertitel, erzeugt SocQ keine neue Spracherkennung (Speech-to-Text).

Kann die offizielle YouTube-API jedes öffentliche Transkript herunterladen?

Nein. Die offizielle YouTube Data API kennt Untertitel-Ressourcen, doch ihre Download-Methode ist für Untertitelspuren gedacht, die der authentifizierte Nutzer verwalten darf. Laut der aktuellen Dokumentation von Google erfordert captions.download eine OAuth-Autorisierung, und der Nutzer muss die Berechtigung haben, das Video zu bearbeiten. Die Methode kostet außerdem 200 Kontingenteinheiten pro Aufruf.

Das funktioniert, wenn Sie den Kanal besitzen oder verwalten. Einen allgemeinen Weg, Untertiteltext beliebiger öffentlicher Videos herunterzuladen, bietet es nicht. Die Autorisierungsanforderungen finden Sie in der offiziellen Dokumentation von Google zum Herunterladen von Untertiteln.

Hilfreich ist es, drei Anwendungsfälle zu trennen:

AnforderungGeeigneter Ansatz
Untertitel zu eigenen Videos verwaltenYouTube Data API mit OAuth
Bereits vorhandenen Untertiteltext ausgewählter öffentlicher Videos abrufenEin verwalteter Transkript-Endpunkt wie der von SocQ
Audio transkribieren, wenn keine Untertitel existierenEine separate Speech-to-Text- oder ASR-Pipeline

SocQ deckt den zweiten Fall ab. Es ruft verfügbaren Transkripttext ab; es behauptet nicht, dass jedes öffentliche Video ein Transkript hat, und es ersetzt fehlende Texte nicht stillschweigend durch neu erzeugten ASR-Text.

Eine YouTube-Transkriptanfrage senden

Der Endpunkt akzeptiert eine oder mehrere öffentliche Video-URLs. Sie können zusätzlich eine bevorzugte Sprache wie en oder zh-CN angeben.

curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.youtube.com/watch?v=arj7oStGLkU"
    ],
    "language": "en"
  }'

Das Senden startet eine asynchrone Aufgabe. Speichern Sie die zurückgegebene task_id; senden Sie denselben Batch nicht erneut, nur weil die Verarbeitung nicht sofort abgeschlossen ist.

Fragen Sie die Aufgabe ab, bis sie einen Endzustand erreicht:

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

queued und running sind normale Zwischenzustände. Nachdem die Aufgabe erfolgreich war, lesen Sie data.results.items. Meldet die Ergebnisseite has_more: true, fordern Sie die nächste Seite mit dem zurückgegebenen next_cursor an.

Die Transkriptantwort verstehen

Ein normalisierter Transkriptdatensatz hat eine stabile Form, die sich speichern lässt, ohne eine YouTube-Seite zu parsen:

{
  "id": "arj7oStGLkU",
  "platform": "youtube",
  "resource": "transcripts",
  "type": "transcript",
  "url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "text": "A plain-text transcript snapshot.",
  "language": "en",
  "available_languages": ["en"],
  "format": "plaintext",
  "transcript_source": "auto_generated",
  "author": {
    "id": "UCAuUUnT6oDeKwE6v1NGQxug",
    "username": "TED",
    "name": "TED",
    "url": "https://www.youtube.com/@TED"
  },
  "created_at": "2016-04-06T00:00:00",
  "collected_at": "2026-07-16T08:00:00Z",
  "extra": {
    "duration_seconds": 843
  }
}

Für die weitere Verarbeitung sind diese Felder am wichtigsten:

  • text: das ausgewählte Transkript als reiner Text.
  • language: die tatsächlich zurückgegebene Sprache, die von der Präferenz abweichen kann.
  • available_languages: nicht leere Transkriptsprachen, die für das Video gefunden wurden.
  • transcript_source: die Klassifizierung der Untertitelquelle, sofern bekannt.
  • id, url, title und author: Quellenkontext für die Nachvollziehbarkeit.
  • created_at und collected_at: Zeitpunkt der Veröffentlichung und der Erfassung.
  • extra.duration_seconds: nützlich für Qualitätsprüfungen und Aufwandsschätzungen.

Die Antwort ist bewusst Klartext. Sie enthält keine verlässlichen Zeitstempel für Segmente und keine Sprecherkennzeichnungen. Erfinden Sie keine genauen Zitatzeiten und wandeln Sie die Antwort nicht in SRT um, als gäbe es Zeitstempeldaten.

Transkripte in der richtigen Sprache abrufen

Die angefragte Sprache ist eine Präferenz, keine Garantie. Ein Produktiv-Workflow sollte immer anhand des zurückgegebenen language weiterleiten.

Wenn Sie zum Beispiel en anfragen:

  1. Es kann eine englische Spur ausgewählt werden.
  2. Es kann eine kompatible Spur der Basissprache ausgewählt werden.
  3. Als Fallback kann eine andere verfügbare Spur zurückkommen.
  4. Es kann kein Datensatz entstehen, wenn es kein brauchbares öffentliches Transkript gibt.

Speichern Sie language und available_languages zu jedem Transkript. Wenn eine exakte Sprachabdeckung zwingend ist, verwerfen oder prüfen Sie Fallback-Ergebnisse, statt sie direkt in Übersetzung, Suche oder ein LLM einzuspeisen.

Bewahren Sie außerdem transcript_source auf. Automatisch erzeugte Untertitel können im großen Maßstab wertvoll sein, doch YouTube weist darauf hin, dass schlechter Ton, nicht unterstützte Sprachen, lange Stille, sich überlagernde Sprecher und mehrere Sprachen automatische Untertitel verhindern oder deren Qualität mindern können. Siehe die Hinweise von YouTube zur Fehlerbehebung bei automatischen Untertiteln.

YouTube-Transkripte im Bulk verarbeiten

Die Bulk-Verarbeitung sollte als Datenpipeline entworfen sein, nicht als Schleife, die davon ausgeht, dass jede URL erfolgreich ist.

Video URLs
   ↓
Validate and deduplicate
   ↓
Submit transcript batches
   ↓
Persist task IDs
   ↓
Poll with backoff
   ↓
Read every result page
   ↓
Validate language and source
   ↓
Store, chunk, index, or export

Beachten Sie diese Praktiken:

  1. URLs vor dem Senden normalisieren. Führen Sie doppelte Watch-, Share- und Embed-URLs auf dieselbe Video-ID zurück.
  2. Batches wiederherstellbar halten. Speichern Sie jeden Batch mit seinen Eingabe-URLs, der Aufgaben-ID, dem Sendezeitpunkt und dem Endstatus.
  3. Mit Backoff abfragen. Vermeiden Sie eine enge Abfrageschleife. Erhöhen Sie die Wartezeit, solange eine Aufgabe in der Warteschlange steht oder läuft.
  4. Teilergebnisse als normal behandeln. Eine erfolgreiche Aufgabe kann weniger Datensätze enthalten als gesendete URLs, weil manche Videos keine brauchbaren Untertitel haben.
  5. Bis zum Ende paginieren. Machen Sie weiter, bis has_more false ist.
  6. Schreibvorgänge idempotent gestalten. Führen Sie ein Upsert über Video-ID plus Transkriptsprache aus, damit Wiederholungen keine Duplikate erzeugen.
  7. Die Erfassungszeit festhalten. Ein Transkript ist eine Momentaufnahme; Untertitel können später bearbeitet oder entfernt werden.

Hier ein minimales Node.js-Muster für die Abfrage:

const headers = {
  Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
  "Content-Type": "application/json"
};

const submitted = await fetch(
  "https://api.socq.ai/v1/youtube/transcripts",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      urls: [
        "https://www.youtube.com/watch?v=arj7oStGLkU",
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      ],
      language: "en"
    })
  }
).then(response => response.json());

let task;
do {
  await new Promise(resolve => setTimeout(resolve, 3000));
  task = await fetch(
    `https://api.socq.ai/v1/tasks/${submitted.task_id}?limit=50`,
    { headers }
  ).then(response => response.json());
} while (["queued", "running"].includes(task.data.status));

if (task.data.status !== "succeeded") {
  throw new Error(`Transcript task ended with ${task.data.status}`);
}

const transcripts = task.data.results.items;

Ergänzen Sie vor dem Produktiveinsatz HTTP-Statusprüfungen, begrenzte Wiederholungen, Cursor-Paginierung, strukturiertes Logging und Abbruchmöglichkeiten.

Fehlende Untertitel und Teilergebnisse behandeln

Ein fehlendes Ergebnis bedeutet nicht automatisch, dass der ganze Batch fehlgeschlagen ist. Häufige Ursachen:

  • Der Creator hat keine Untertitel bereitgestellt, und automatische Untertitel sind nicht verfügbar.
  • Die Untertitel eines kürzlich veröffentlichten Videos werden noch verarbeitet.
  • Die gesprochene Sprache wird nicht unterstützt oder wurde nicht erkannt.
  • Die Tonqualität ist schlecht, Sprecher überlagern sich, oder das Video enthält mehrere Sprachen.
  • Das Video ist privat, gelöscht, eingeschränkt oder in der Erfassungsumgebung nicht verfügbar.
  • Die angefragte Sprache fehlt, und es gibt keinen brauchbaren Fallback.

Klassifizieren Sie Fehler, statt sie endlos zu wiederholen:

FehlerartEmpfohlene Maßnahme
Keine brauchbaren UntertitelAls nicht verfügbar markieren; optional an einen separaten ASR-Workflow weiterleiten
Angefragte Sprache fehltavailable_languages prüfen oder einen kontrollierten Fallback akzeptieren
Vorübergehender Aufgaben- oder NetzwerkfehlerMit exponentiellem Backoff und Obergrenze wiederholen
Privates, gelöschtes oder eingeschränktes VideoWiederholungen beenden und den Grund festhalten
Leeres oder verdächtiges TranskriptZur Validierung in Quarantäne stellen

Geben Sie ASR-Ausgaben nicht als YouTube-Untertitel aus, ohne die Quelle zu nennen. Die Unterscheidung ist wichtig für Genauigkeitsprüfungen und Zitate.

Transkriptdaten sicher exportieren

Klartext-Ergebnisse lassen sich nach TXT, JSON oder CSV exportieren.

Schreiben Sie für TXT das Feld text und führen Sie einen separaten Metadatensatz. Bewahren Sie für JSON das vollständige normalisierte Objekt auf. Verwenden Sie für CSV eine Zeile pro Video mit Feldern wie id, url, title, language, transcript_source, text und collected_at.

SRT und VTT erfordern zeitlich markierte Segmente. Weil der Transkript-Endpunkt von SocQ Klartext statt Segmente liefert, lässt sich aus dieser Antwort allein kein originalgetreuer Export mit Zeitmarken erzeugen.

Speichern Sie für durchsuchbare Archive nicht nur den Transkripttext. Halten Sie an jedem abgeleiteten Datensatz Video-ID, kanonische URL, Titel, Kanal, Sprache, Quelle, Veröffentlichungszeitpunkt und Erfassungszeitpunkt fest.

Transkripte für Suche und RAG aufbereiten

Rohe Transkripte sind meist zu groß und zu verrauscht, um sie als ein Block an ein Modell zu senden. Ein besserer Workflow:

  1. Leerraum normalisieren, ohne die Quelle umzuschreiben.
  2. Unerwartet kurzen oder leeren Text erkennen.
  3. Den Text in sich überlappende semantische Chunks teilen.
  4. An jeden Chunk die Quellmetadaten anhängen.
  5. Embeddings erzeugen.
  6. Die Chunks in einem Such- oder Vektorindex speichern.
  7. Mit jeder Antwort die Video-URL und die Transkript-Metadaten zurückgeben.

Ein brauchbarer Chunk-Datensatz sieht so aus:

{
  "video_id": "arj7oStGLkU",
  "video_url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "language": "en",
  "transcript_source": "auto_generated",
  "chunk_index": 12,
  "text": "The transcript text for this chunk...",
  "collected_at": "2026-07-16T08:00:00Z"
}

Da die Quellantwort keine Segment-Zeitstempel enthält, zitieren Sie das Video, statt einen genauen Zeitbereich zu behaupten. Wenn zeitgenaue Zitate unverzichtbar sind, wählen Sie eine Quelle mit verifizierten Segmenten oder ergänzen Sie einen separaten Alignment-Schritt.

Vor dem Abruf von Transkripten die passende YouTube-API wählen

Die Transkripterfassung ist oft der letzte Schritt eines größeren Discovery-Workflows:

Das verringert unnötige Transkriptanfragen und hält den endgültigen Datensatz an ausdrückliche Auswahlkriterien gebunden.

Ein Transkript-Dataset aktuell halten

Ein Transkriptarchiv braucht eine ausdrückliche Aktualisierungsrichtlinie. Untertitel können nach der Veröffentlichung korrigiert werden, neue Sprachspuren können hinzukommen, und ein zuvor verfügbares Video kann entfernt oder eingeschränkt werden. Alles täglich neu abzurufen ist Verschwendung, doch die erste Antwort als endgültig zu behandeln, kann einen Suchindex mit veraltetem oder nicht nachvollziehbarem Text zurücklassen.

Wählen Sie das Aktualisierungsintervall passend zum Anwendungsfall:

  • Speichern Sie bei einem einmaligen Recherche-Dataset die Erfassungszeit und verzichten Sie auf automatische Aktualisierungen, sofern die Analyse sie nicht erfordert.
  • Rufen Sie bei einem durchsuchbaren Kanalarchiv aktuelle Videos häufiger erneut ab, weil Untertitel oft kurz nach der Veröffentlichung bearbeitet werden.
  • Prüfen Sie bei Compliance- oder Zitier-Workflows die Quelle erneut, bevor Sie ein Zitat veröffentlichen oder eine folgenreiche Entscheidung treffen.
  • Behalten Sie bei langlebigen RAG-Systemen einen Content-Hash, damit ein unverändertes Transkript keine unnötige neue Aufteilung und kein neues Embedding auslöst.

Ändert sich ein aktualisiertes Transkript, legen Sie eine neue Version an oder behalten Sie einen Audit-Eintrag, statt die einzige Kopie stillschweigend zu überschreiben. Speichern Sie mindestens Video-ID, Transkriptsprache, Untertitelquelle, Erfassungszeit, Text-Hash und Pipeline-Version. Liefert ein Video kein Ergebnis mehr, markieren Sie den vorhandenen Datensatz zum letzten Prüfzeitpunkt als nicht verfügbar; gehen Sie nicht davon aus, dass das historische Transkript immer ungültig war.

Checkliste für den Produktivbetrieb

Prüfen Sie vor einem Job mit hohem Volumen:

  • Die Eingaben sind öffentliche YouTube-Video-URLs.
  • Die URLs wurden normalisiert und dedupliziert.
  • Aufgaben-IDs und ursprüngliche Eingaben werden gespeichert.
  • Die Abfrage arbeitet mit Wartezeit und begrenzten Wiederholungen.
  • Die Cursor-Paginierung läuft weiter, bis has_more false ist.
  • Fehlende Ergebnisse werden getrennt von Aufgabenfehlern behandelt.
  • Die zurückgegebene Sprache wird validiert.
  • Automatisch erzeugte Untertitel sind gekennzeichnet.
  • Jeder Chunk und jeder Export behält die Quellmetadaten.
  • Ihre Nutzung der Inhalte respektiert geltende Rechte, Datenschutzerwartungen und Plattformbedingungen.

Häufig gestellte Fragen (FAQ)

Gibt es eine offizielle YouTube-Transkript-API?

YouTube hat eine offizielle Captions API, doch das Herunterladen einer Untertitelspur erfordert OAuth und die Berechtigung, das Video zu bearbeiten. Sie ist keine allgemeine Transkript-API für beliebige öffentliche Videos.

Kann ich ein YouTube-Transkript ohne OAuth herunterladen?

Die SocQ YouTube Transcripts API verwendet einen SocQ-API-Schlüssel statt einer YouTube-OAuth-Freigabe. Sie ruft verfügbaren Transkripttext aus ausgewählten öffentlichen Video-URLs ab.

Kann SocQ ein Transkript erzeugen, wenn ein Video keine Untertitel hat?

Nein. Der Endpunkt liefert verfügbaren öffentlichen Transkripttext. Ein Video ohne brauchbare Untertitel liefert unter Umständen kein Ergebnis. Nutzen Sie einen separat ausgewiesenen Speech-to-Text-Workflow, wenn Sie einen ASR-Fallback brauchen.

Kann ich eine bestimmte Sprache anfragen?

Ja. Sie können optional eine BCP-47-Sprache wie en oder zh-CN senden, doch die tatsächlich zurückgegebene Sprache kann abweichen. Prüfen Sie immer language und available_languages.

Enthält die Antwort Zeitstempel und Sprecherkennzeichnungen?

Nein. Das Antwortformat ist normalisierter Klartext und bietet weder Segment-Zeitstempel noch garantierte Sprecherkennzeichnungen.

Kann ich mehrere Transkripte in einer Anfrage abrufen?

Ja. Senden Sie mehrere öffentliche Video-URLs in urls, speichern Sie die Aufgaben-ID und lesen Sie jede fertige Ergebnisseite, nachdem die asynchrone Aufgabe erfolgreich war.

Was kostet die YouTube Transcripts API?

Die aktuelle Endpunkt-Dokumentation nennt 0,5 Credits pro normalisiertem Transkriptergebnis. Prüfen Sie die Live-Seite des Endpunkts, bevor Sie eine Produktiv-Arbeitslast schätzen, denn Preise können sich ändern.

YOUTUBE API

Workflow mit einer öffentlichen YouTube-URL testen

Senden Sie öffentliche Eingaben und erhalten Sie normalisierte Datensätze mit nachvollziehbarem Quellkontext.

YouTube-APIs ansehen