YouTube-Transkript-API in Python: 10 Zeilen mit requests

youtube_transcript_api._errors.IpBlocked:
Could not retrieve a transcript for the video.
YouTube is blocking requests from your IP.

Wenn dieser Traceback dich hierher geführt hat, willkommen. Es ist der Standard-Fehlermodus des beliebten pip-Pakets, sobald dein Code von deinem Laptop verschwindet und auf AWS, GCP oder irgendeinem anderen Rechenzentrum landet. Dieser Beitrag zeigt den anderen Weg: eine gehostete YouTube-Transkript-API, die du aus Python mit nichts anderem als requests aufrufen kannst. Am Ende hast du ein zehn-zeiliges Skript, das jede YouTube-URL in Transkript-Text verwandelt, plus richtige Branches für Rate Limits und Videos ohne Untertitel.

Warum die pip-Bibliothek in der Produktion scheitert

youtube-transcript-api kratzt YouTube direkt von der Maschine ab, auf der es läuft. Lokal ist das kein Problem. Stellen es bereit, und YouTubes Bot-Erkennung markiert den IP-Bereich deines Cloud-Anbieters innerhalb von Tagen, manchmal Minuten. Ich habe die blutigen Details in warum die YouTube-Transkript-API blockiert wird aufgeschrieben — kurz gesagt: du endest damit, dass du Wohnproxys mietest, um öffentliche Untertitel zu lesen, was absurd ist.

youtube2text.org macht den YouTube-Teil serverseitig. Dein Code macht einen HTTPS-Aufruf und bekommt JSON zurück.

Die zehn Zeilen

Kein Konto nötig zum Ausprobieren — es gibt einen Demo-Key-Endpunkt:

import requests

API = "https://youtube2text.org/api/transcribe"
KEY = requests.get("https://youtube2text.org/api/demo-key").json()["apiKey"]

resp = requests.get(API, params={"url": "https://youtu.be/dQw4w9WgXcQ"},
                    headers={"x-api-key": KEY}, timeout=60)
resp.raise_for_status()
result = resp.json()["result"]
print(result["title"])
print(result["content"][:300])

Der url-Parameter akzeptiert jede YouTube-URL-Form — watch?v=, youtu.be, Shorts, Embeds — oder eine nackte 11-stellige Video-ID. Die Antwort gibt dir videoId, title, pubDate, content, contentSize und ein truncated-Flag.

Ein Vorbehalt zu diesem Demo-Key: Er wird von allen geteilt und ist auf 5 Videos pro Monat pro IP begrenzt. Gut zum Kick-off, sinnlos für irgendetwas Echtes.

429 und 404 wie ein Profi handhaben

raise_for_status() ist für eine Demo okay, aber Fehler kommen als strukturiertes JSON mit einem code zurück, auf den du branchen kannst:

import time

resp = requests.get(API, params={"url": video_url},
                    headers={"x-api-key": KEY}, timeout=60)
body = resp.json()

if resp.status_code == 200:
    transcript = body["result"]["content"]
elif resp.status_code == 429:
    time.sleep(body["error"]["retryAfterSeconds"])  # then retry
elif resp.status_code == 404:
    if body["error"]["code"] == "TRANSCRIPT_UNAVAILABLE":
        transcript = None  # video exists, but has no captions — skip it
    else:
        raise ValueError(f"No such video: {video_url}")  # VIDEO_NOT_FOUND
else:
    raise RuntimeError(body["error"]["message"])

TRANSCRIPT_UNAVAILABLE verdient einen Moment der Ehrlichkeit: Transkripte stammen aus Youtub's Untertitelspuren (manuell oder automatisch generiert), und manche Videos haben einfach keine. Keine API kann Text zaubern, der nicht da ist — dafür brauchst du echte Spracherkennung, die ich in Whisper vs YouTube Untertitel verglichen habe. Erneut zu versuchen hilft nicht, also tun Sie es nicht.

maxChars und LLM-Token-Budgets

Wenn das Transkript in einen Prompt geht, kümmert dich die Größe. Ein drei-Stunden-Podcast-Transkript wird fröhlich 100k Token auffressen. Der maxChars-Parameter begrenzt die Ausgabe — Standard und Maximum sind beide 150000:

resp = requests.get(API,
    params={"url": video_url, "maxChars": 20000},
    headers={"x-api-key": KEY}, timeout=60)

Nach der groben 4-Zeichen-pro-Token-Regel landet maxChars=20000 um die 5k Token. Überprüfe result["truncated"], um zu wissen, ob du das Ganze bekommen hast. Wenn du das in eine Abruf-Pipeline drahtest statt in einen einzelnen Prompt, behandelt der LangChain-Integrations-Beitrag das Chunking richtig.

Weg vom Demo-Key

Wenn 5 gemeinsame Videos pro Monat nicht mehr ausreichen, melde dich mit Google unter youtube2text.org/app/keys an und präge deinen eigenen Key — keine Telefonnummer, keine Kreditkarte. Das kostenlose Tier sind 5 Videos pro Monat pro Schlüssel; bezahlte Stufen beginnen bei $5,99 für 50. Die zehn Zeilen oben ändern sich nicht, nur die Zeichenkette in der Kopfzeile.