API YouTube Transcript in Python: 10 righe con requests

Script Python che recupera una trascrizione YouTube come JSON con la libreria requests

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

Se quella traceback ti ha portato qui, benvenuto. È la modalità di errore standard del noto pacchetto pip nel momento in cui il tuo codice lascia il tuo laptop e atterra su AWS, GCP o qualsiasi altro IP del datacenter. Questo articolo mostra l'altra strada: un'API YouTube Transcript ospitata che chiami da Python con nient'altro che requests. Alla fine avrai uno script di dieci righe che trasforma qualsiasi URL YouTube in testo della trascrizione, più i rami appropriati per i limiti di velocità e i video senza didascalie.

Perché la libreria pip muore in produzione

youtube-transcript-api raschia YouTube direttamente dalla macchina su cui viene eseguita. Localmente va bene. Distribuiscila, e la rilevazione di bot di YouTube contrassegna l'intervallo IP del tuo provider cloud entro giorni, a volte minuti. Ho scritto i dettagli completi in perché l'API YouTube Transcript viene bloccata — versione breve: finisci per noleggiare proxy residenziali per leggere didascalie pubbliche, il che è assurdo.

youtube2text.org fa la parte rivolta a YouTube lato server. Il tuo codice effettua una sola chiamata HTTPS e riceve JSON indietro.

Le dieci righe

Nessun account necessario per provarlo — c'è un endpoint della chiave demo:

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])

Il parametro url accetta qualsiasi forma di URL YouTube — watch?v=, youtu.be, shorts, embed — o un ID video nudo di 11 caratteri. La risposta ti dà videoId, title, pubDate, content, contentSize e un flag truncated.

Una precisazione su quella chiave demo: è condivisa da tutti ed è limitata a 5 video al mese per IP. Va bene per provare, inutile per qualsiasi cosa seria.

Gestire 429 e 404 come un adulto

raise_for_status() va bene per una demo, ma gli errori vengono restituiti come JSON strutturato con un code su cui puoi fare il branch:

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 merita un momento di onestà: le trascrizioni provengono dai tracciamenti didascalici di YouTube (manuali o generati automaticamente), e alcuni video semplicemente non ne hanno uno. Nessuna API può coniugare testo che non c'è — per quelli avresti bisogno di vero speech-to-text, che ho confrontato in Whisper vs didascalie YouTube. Non aiuta il ritentativo, quindi non provare.

maxChars e budget dei token LLM

Se la trascrizione è diretta verso un prompt, ti interessa la dimensione. Una trascrizione di podcast di tre ore consumerà allegramente 100k token. Il parametro maxChars limita l'output — il valore predefinito e massimo sono entrambi 150000:

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

Con la regola approssimativa di 4 caratteri per token, maxChars=20000 arriva a circa 5k token. Controlla result["truncated"] per sapere se hai ottenuto il tutto. Se stai collegando questo in una pipeline di recupero invece di un singolo prompt, il post di integrazione LangChain copre il chunking correttamente.

Scappare dalla chiave demo

Quando 5 video condivisi al mese smettono di essere sufficienti, accedi con Google su youtube2text.org/app/keys e crea la tua chiave — nessun numero di telefono, nessuna carta di credito. Il livello gratuito è 5 video al mese per chiave; i livelli a pagamento iniziano a $ 5,99 per 50. Le dieci righe precedenti non cambiano, solo la stringa nell'intestazione.