youtube-transcript-api è una libreria Python gratuita e open source che recupera i sottotitoli di un video di YouTube: pip install youtube-transcript-api, poi YouTubeTranscriptApi().fetch(video_id). Dal tuo computer funziona bene, ma da un server cloud YouTube la blocca spesso con RequestBlocked o IpBlocked, e non aiuta con i video senza sottotitoli.
L'abbiamo eseguita da una macchina cloud il 21 novembre 2026, poi abbiamo fatto passare gli stessi due video dalla nostra API ospitata, dalla stessa macchina. Ecco cosa ha fatto ciascuna, come usare la libreria e quando conviene un'API ospitata.
Che cos'è youtube-transcript-api?
È una libreria Python di Jonas Depoix, su GitHub e PyPI, con licenza MIT. La versione attuale è la 1.2.5, per Python 3.8 e successivi.
- Legge i sottotitoli che YouTube ha già, quelli del canale o quelli automatici di YouTube.
- Non richiede chiave API né browser headless.
- Elenca le lingue dei sottotitoli di un video, preferisce una lingua a un'altra e usa la traduzione automatica di YouTube.
- Restituisce testo, JSON, SRT o WebVTT e ha uno strumento da riga di comando.
Il README è chiaro sul compromesso: usa una parte non documentata del player web di YouTube, quindi non c'è "no guarantee that it won't stop working tomorrow".
Come si usa?
pip install youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import SRTFormatter
ytt_api = YouTubeTranscriptApi()
# English if it exists, else German
transcript = ytt_api.fetch("aircAruvnKk", languages=["en", "de"])
for snippet in transcript:
print(snippet.start, snippet.text)
print(SRTFormatter().format_transcript(transcript))
Da riga di comando, youtube_transcript_api aircAruvnKk --languages en --format json > transcript.json fa lo stesso. Il README spiega come elencare le lingue, tradurre e il resto.
Perché fallisce con IpBlocked sul mio server?
Perché YouTube blocca la maggior parte delle richieste dai provider cloud. Il README della libreria lo dice chiaramente: YouTube "has started blocking most IPs that are known to belong to cloud providers (like AWS, Google Cloud Platform, Azure, etc.)", quindi una volta pubblicato il codice incontrerai "most likely" errori RequestBlocked o IpBlocked. Anche un IP domestico può essere bloccato dopo troppe richieste.
L'abbiamo visto di persona. Il 21 novembre 2026 abbiamo installato la versione 1.2.5 su una macchina cloud e chiesto due lezioni pubbliche:
Stessa macchina, stessi due video, 21 novembre 2026 (UTC).
Entrambe le chiamate hanno dato IpBlocked dopo circa 1,1 secondi. Una semplice richiesta a youtube.com da quella macchina è stata reindirizzata alla pagina di "traffico insolito" di Google: era YouTube a rifiutare la macchina, non un bug della libreria.
La soluzione del README sono i proxy, e consiglia proxy residenziali a rotazione, perché YouTube banna i proxy statici dopo un uso prolungato. Funziona, ma significa un altro servizio a pagamento, un altro account e blocchi da tenere d'occhio.
Cos'altro può fermarla?
- Niente sottotitoli. La libreria legge sottotitoli; non trascrive l'audio. Sottotitoli disattivati danno
TranscriptsDisabled, una lingua mancanteNoTranscriptFound. - Video con limiti di età. Il README dice che l'accesso tramite cookie, necessario per questi video, è "currently not available" dopo modifiche lato YouTube.
- Cambiamenti di YouTube. Poiché usa un'interfaccia non documentata, un aggiornamento di YouTube può romperla finché non esce una nuova versione.
Niente di tutto questo è un motivo per evitarla in uno script sul tuo portatile. È un motivo per prevederlo prima di metterla in un prodotto.
Cosa posso usare quando viene bloccata?
Un'API di trascrizione ospitata, che fa il recupero dal suo lato. La nostra è l'API di YouTubeTranscript.dev. Dalla stessa macchina cloud, pochi minuti prima, gli stessi due video:
| Video | Durata | Tempo | Parole | Righe con timestamp | Crediti |
|---|---|---|---|---|---|
| But what is a neural network? (3Blue1Brown) | 18:40 | 4,2 secondi | 3.357 | 286 | 1 |
| 1. What is Computation? (MIT OpenCourseWare) | 43:06 | 4,2 secondi | 6.363 | 887 | 1 |
| Lo stesso video di 3Blue1Brown, richiesto di nuovo | 18:40 | 1,3 secondi | 3.357 | 286 | 0 |
Come abbiamo misurato: una richiesta a POST /api/v2/transcribe per ciascuno, solo sottotitoli e timestamp attivi, cronometrata con curl dall'invio alla risposta completa. I crediti sono quelli indicati da ogni risposta. Una prova ciascuno, quindi prendi i tempi come esempi.
La chiamata da Python:
import requests
r = requests.post(
"https://www.youtubetranscript.dev/api/v2/transcribe",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"video": "aircAruvnKk", "mode": "auto", "format": {"timestamp": True}},
)
data = r.json()["data"]
for seg in data["transcript"]["segments"]:
print(seg["start"], seg["text"]) # start and end are in milliseconds
Il compromesso è il costo: la libreria è gratis, l'API costa 1 credito per video con sottotitoli, con 10 crediti gratis al mese e piani a pagamento da 5 dollari per 500. Con "mode": "auto" trascrive anche i video senza sottotitoli, a 1 credito ogni 2 minuti di audio. C'è un SDK Python se preferisci non scrivere la richiesta.
Come integro un'API di trascrizione nel mio prodotto?
Lo stesso schema vale con qualsiasi API:
- Tieni la chiave sul server. I tuoi utenti mandano un link al tuo backend, che chiama l'API. Non mettere mai la chiave nel codice del browser o dell'app.
- Accetta qualsiasi formato di link. Passa il link così come l'utente l'ha scritto; la nostra accetta URL completi, youtu.be, Shorts, embed e ID semplici (l'elenco completo).
- Salva la trascrizione per ID video. Quasi tutti i prodotti richiedono sempre gli stessi video popolari. Da noi, una trascrizione che il tuo account ha già non costa nulla da richiedere di nuovo, come mostra la terza riga, ma una copia locale è ancora più veloce.
- Tratta i video senza sottotitoli come un lavoro. Trascrivere l'audio richiede più tempo di quanto una richiesta web dovrebbe attendere. Invia
mode: "auto"con unwebhook_url, oppure interroga l'ID del lavoro restituito, e mostra all'utente l'avanzamento. - Usa i batch quando sono tanti. Per una playlist, un canale o un arretrato usa l'endpoint batch invece di un ciclo di chiamate singole, così resti nel limite di frequenza.
La documentazione dell'API descrive ogni campo, e la nostra guida all'API speech-to-text misura precisione e costi su audio senza sottotitoli.
Quale dovrei usare?
| Se stai... | Usa |
|---|---|
| eseguendo uno script sul tuo computer, pochi video alla volta | youtube-transcript-api |
| pubblicando su un server cloud, una funzione serverless o un prodotto | Un'API ospitata, oppure la libreria con proxy residenziali a rotazione |
| gestendo video senza sottotitoli | Un servizio che trascrive l'audio |
| scaricando playlist o canali interi | Un'API ospitata con endpoint batch |
Riepilogo
- youtube-transcript-api è gratuita, con licenza MIT e semplice:
YouTubeTranscriptApi().fetch(video_id). - Su un server cloud YouTube la blocca spesso; sulla nostra macchina cloud entrambi i video hanno dato
IpBlockedin circa 1,1 secondi. La soluzione suggerita sono i proxy. - Legge solo sottotitoli esistenti, e i video con limiti di età per ora sono esclusi.
- Un'API ospitata ha restituito gli stessi video dalla stessa macchina in 4,2 secondi ciascuno, per 1 credito ciascuno, e gestisce anche i video senza sottotitoli.
Domande frequenti
Che cos'è youtube-transcript-api?+
Una libreria Python open source (licenza MIT) che recupera i sottotitoli che un video ha già su YouTube, anche quelli automatici, senza chiave API e senza browser. Si installa con pip install youtube-transcript-api e si usa con YouTubeTranscriptApi().fetch(video_id).
Perché youtube-transcript-api dà RequestBlocked o IpBlocked?+
Perché YouTube blocca la maggior parte delle richieste dagli indirizzi IP dei provider cloud, e può bloccare qualsiasi IP che faccia troppe richieste. Il README della libreria lo dice e suggerisce proxy residenziali a rotazione. Dalla nostra macchina cloud, il 21 novembre 2026, entrambi i video provati hanno dato IpBlocked in circa 1,1 secondi.
youtube-transcript-api può trascrivere un video senza sottotitoli?+
No. Legge sottotitoli già esistenti. Un video con sottotitoli disattivati dà TranscriptsDisabled, uno senza la tua lingua NoTranscriptFound. Per ricavare testo dall'audio serve un servizio di sintesi vocale in testo.
youtube-transcript-api è gratuito?+
Sì, la libreria è gratuita e con licenza MIT. Su un server di solito bisogna pagare dei proxy, perché gli IP cloud sono bloccati.
Cosa posso usare al posto di youtube-transcript-api su un server?+
Un'API di trascrizione ospitata che fa il recupero per te. Dalla stessa macchina su cui la libreria era bloccata, l'API di YouTubeTranscript.dev ha restituito entrambi i video in 4,2 secondi ciascuno, per 1 credito ciascuno, e una richiesta ripetuta in 1,3 secondi gratis.
Come integro un'API di trascrizione nel mio prodotto?+
Tieni la chiave API sul tuo server, invia il link del video a un endpoint, salva la trascrizione per ID video così non paghi mai due volte, gestisci i video senza sottotitoli come un lavoro asincrono con webhook e usa un endpoint batch per molti video insieme.