Transkripte über die YouTube Data API: Warum captions.download scheitert

Terminal zeigt eine 403-Forbidden-Antwort des captions.download-Endpoints der YouTube Data API

Wenn du versuchst, Transkripte über die YouTube Data API zu bekommen, bist du vermutlich schon gegen die Wand gelaufen: captions.list liefert fröhlich Untertitel-Track-IDs für jedes Video, aber sobald du captions.download auf einen davon aufrufst, bekommst du einen 403. Du prüfst deinen API-Key doppelt, ergänzt den youtube.force-ssl-Scope, versuchst OAuth — immer noch 403. Das ist kein Bug und kein Kontingent-Problem. Es ist Absicht, und die Doku versteckt den entscheidenden Punkt.

Die Einschränkung, präzise

captions.download verlangt ein OAuth-Token von einem Account, dem das Video gehört. Nicht irgendein authentifizierter Account — der Kanalinhaber (oder ein Content-Manager mit Rechten daran). Die Captions-Endpoints existieren, damit Creator die Untertitelspuren ihrer eigenen Uploads verwalten können: eine .srt hochladen, einen Tippfehler korrigieren, eine schlechte Auto-Übersetzung löschen. Untertitel beliebiger fremder Videos herunterzuladen war nie Teil des Vertrags.

Die Fehlermeldung sagt es klar, wenn man sie aufmerksam liest:

The permissions associated with the request are not sufficient
to download the caption track.

Der übliche Eskalationspfad — API-Key → OAuth als du selbst → breitere Scopes → Service-Account — führt also nirgendwohin. Jede Stufe scheitert am selben Ownership-Check. Ich habe einen Nachmittag daran verbrannt, bevor ich es akzeptiert habe, und dem Stack-Overflow-Traffic nach zu urteilen ging es dem halben Internet genauso.

Wofür captions.list weiterhin taugt

Um der Data API gerecht zu werden: captions.list funktioniert mit einem schlichten API-Key und kostet etwa 50 Kontingent-Einheiten. Es sagt dir, welche Tracks existieren, ihre Sprachen und ob sie automatisch generiert (trackKind: "asr") oder von Menschen hochgeladen sind. Das ist als Pre-Flight-Check wirklich nützlich — wenn ein Video gar keine Tracks hat, weißt du vorab, dass du Speech-to-Text statt Untertitel-Extraktion brauchen wirst. Die Data API bleibt auch das richtige Werkzeug für Suche, Playlist-Auflistung und Metadaten. Sie gibt dir nur nicht den Transkript-Text.

Option 1: Untertitel so holen, wie es der Player tut

Der Videoplayer erhält Untertiteldaten offensichtlich ohne das OAuth-Token des Besitzers, und Bibliotheken wie youtube-transcript-api (Python) holen sie auf demselben Weg. Auf deinem Laptop funktioniert das gut und braucht drei Zeilen.

Der Haken zeigt sich in Produktion: YouTube stellt Anfragen aus Datacenter-IP-Bereichen aggressiv infrage. Deploye dieselben drei Zeilen auf AWS, GCP oder Heroku und du siehst bald „Sign in to confirm you're not a bot" und IpBlocked-Fehler. Diesen Fehlermodus und die Workarounds habe ich separat aufgeschrieben in warum youtube-transcript-api in der Cloud blockiert wird — Kurzfassung: Es ist mit Residential-Proxys lösbar, aber das ist ein eigenes Projekt.

Option 2: eine gehostete Transkript-API

Wenn du einfach nur Text aus einer URL willst, umgeht ein gehosteter Endpoint beide Probleme — keine Ownership-Anforderung, kein Proxy-Babysitting. youtube2text.org betreibt den Untertitel-Abruf serverseitig hinter rotierenden Residential-Proxys, deine Anfrage kann also herkommen, wo sie will:

# grab a free demo key (shared, 5 videos/month per IP)
curl -s https://youtube2text.org/api/demo-key

# fetch a transcript
curl -s "https://youtube2text.org/api/transcribe?url=https://www.youtube.com/watch?v=VIDEO_ID" \
  -H "x-api-key: yt_YOUR_KEY"

Die Antwort ist schlichtes JSON:

{"result": {"videoId": "...", "title": "...", "pubDate": "...",
            "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

Hat das Video schlicht keine Untertitel, bekommst du TRANSCRIPT_UNAVAILABLE mit einem 404 — dieselbe Situation, die captions.list als leere Track-Liste gezeigt hätte, nur in einem Aufruf statt zwei erkannt.

Eine längere Anleitung mit Fehlerbehandlung gibt es in YouTube-Transkripte mit curl extrahieren, und eine Python-Version im Migrationsguide für youtube-transcript-api, falls requests-basierter Code eher dein Tempo ist.

Ein vernünftiges kombiniertes Setup

Was ich heute tatsächlich bauen würde, nachdem ich das von beiden Enden her durchgekämpft habe:

Data API für Discovery — Suche, Kanal-Uploads, Playlists, Veröffentlichungsdaten. Sie ist zuverlässig und für Metadaten großzügig bemessen.
Ein Transkript-Endpoint (gehostet, oder selbst gescrapt mit Proxys, wenn dir das Spaß macht) für den eigentlichen Text.
Speech-to-Text als Fallback nur für Videos ganz ohne Untertitel.

captions.download zum Mittelstück zwingen zu wollen ist der eine Pfad, der für Videos, die dir nicht gehören, kategorisch nicht funktionieren kann — kein Scope, Key oder Konsolen-Setting ändert daran etwas.

Wenn du deinen eigenen Key statt des geteilten Demo-Keys willst: Anmeldung nur per Google unter youtube2text.org/app/keys — keine Telefonnummer, keine Karte. Der Free-Tier bietet 5 Videos/Monat; bezahlte Pläne starten bei 5,99 $ für 50.