youtube-transcript-api bloccata da YouTube? 4 soluzioni che funzionano

L'errore: funziona in locale, bloccato in produzione

La libreria Python youtube-transcript-api è il modo più diffuso per recuperare le trascrizioni di YouTube in modo programmatico. Sulla tua macchina locale di solito funziona alla perfezione. Ma appena il codice gira su un server cloud, le richieste iniziano a fallire con eccezioni come IpBlocked, RequestBlocked o TooManyRequests, spesso con un messaggio che indica che YouTube sta bloccando il tuo IP.

Lo stesso vale per qualsiasi approccio basato su scraping: i pacchetti Node.js per le trascrizioni, l'estrazione dei sottotitoli con yt-dlp e gli scraper scritti in casa vanno tutti a sbattere contro lo stesso muro. Il problema non è il tuo codice: è il posto da cui partono le richieste.

Se il tuo carico gira su AWS Lambda, Google Cloud Run, Vercel, Railway, Fly.io o un qualsiasi VPS, YouTube vede l'indirizzo IP di un datacenter. Quegli intervalli di IP sono pubblici, pesantemente abusati dai bot e bloccati in blocco. Le connessioni residenziali (come il Wi-Fi di casa) vengono bloccate raramente: ecco perché qui "sulla mia macchina funziona" è letteralmente vero.

Perché YouTube blocca queste richieste

Le trascrizioni di YouTube vengono servite da un endpoint interno e non autenticato, mai pensato per l'uso da parte di terzi. Non esiste un'API pubblica ufficiale per ottenere le trascrizioni di video qualsiasi: l'endpoint captions della Data API ufficiale richiede l'autorizzazione OAuth del proprietario del video, quindi funziona solo per i tuoi video.

Proprio perché quell'endpoint interno è gratuito e senza autenticazione, viene martellato da aziende di AI, tool SEO e scraper. YouTube risponde nell'unico modo che ha a disposizione: rate limiting aggressivo, blocco in massa degli intervalli IP dei datacenter e modifiche periodiche all'endpoint che mandano in crash le librerie di scraping da un giorno all'altro.

Il risultato è che qualsiasi soluzione self-hosted vive in un eterno gioco del gatto col topo. Le quattro soluzioni qui sotto sono ordinate dalla più fai-da-te alla più gestita.

Soluzione 1: instradare le richieste su proxy residenziali

La soluzione fai-da-te classica è far passare le richieste attraverso proxy residenziali a rotazione, così YouTube vede normali IP domestici invece del tuo server. Le versioni recenti di youtube-transcript-api lo supportano direttamente: basta passare una configurazione proxy alla creazione del client (la libreria include l'helper WebshareProxyConfig, oppure puoi usare GenericProxyConfig con qualsiasi proxy HTTP/SOCKS).

Funziona, ma ha costi reali. La banda dei proxy residenziali è cara (di solito qualche dollaro per GB), la qualità cambia moltissimo da un fornitore all'altro e ti ritrovi una nuova fonte di guasti: quando un IP proxy viene bloccato a metà richiesta, servono logica di retry, health check e failover tra fornitori. Con volumi bassi può anche essere l'opzione più lenta, perché ogni richiesta fa un salto in più nella rete proxy.

Scegli questa strada se ti serve il controllo completo, hai tempo di ingegneria da dedicare alla manutenzione e i volumi sono abbastanza alti da giustificare il lavoro di setup.

Soluzione 2: eseguire il fetcher su una connessione residenziale

Una variante più semplice: fai girare la parte che recupera le trascrizioni su una macchina con IP residenziale — un Raspberry Pi a casa, un computer in ufficio o un mini-PC economico — e falle inviare i risultati alla tua infrastruttura cloud tramite una coda o un webhook.

Così eviti del tutto i costi dei proxy e per carichi piccoli e personali (per esempio trascrivere video per i tuoi appunti o per una piccola newsletter) funziona sorprendentemente bene. Gli svantaggi sono evidenti: è un singolo punto di guasto fisico, non scala ed è un'architettura scomoda per un prodotto in produzione.

Soluzione 3: usare la cache e fare backoff sugli errori

Qualunque metodo tu usi per recuperare le trascrizioni, due accorgimenti riducono drasticamente i blocchi. Primo: metti in cache ogni trascrizione che scarichi. Le trascrizioni non cambiano quasi mai, quindi non ha senso richiedere due volte lo stesso video. Una semplice tabella di database indicizzata sull'ID del video elimina gran parte del traffico ripetuto.

Secondo: tratta i blocchi come un segnale, non come un errore da riprovare subito. Un backoff esponenziale con jitter (aspetta 1s, poi 2s, 4s, 8s...) ti tiene sotto il radar. Continuare a martellare l'endpoint dopo un blocco è il modo più rapido per far bandire l'intero intervallo di IP.

Attenzione: questa è una mitigazione, non una soluzione. Su un IP di datacenter può essere bloccata già la prima richiesta. Combinala con una delle altre tre soluzioni.

Soluzione 4: usare un'API di trascrizione hosted (nessuna infrastruttura da mantenere)

L'opzione gestita: lascia che a recuperare le trascrizioni sia un servizio che il problema degli IP l'ha già risolto. ParseJet espone un solo endpoint — POST /v1/parse/youtube con l'URL del video — e restituisce in JSON la trascrizione completa con titolo, canale e durata del video. Blocchi, gestione dei proxy e modifiche all'endpoint sono gestiti lato server, quindi il tuo codice sono tre righe e tre righe resta.

Migrare da youtube-transcript-api richiede pochi minuti: sostituisci la chiamata alla libreria con una singola POST HTTP (funziona da Python, Node.js o qualsiasi cosa parli HTTP, comprese le funzioni serverless, dove l'approccio a libreria viene bloccato più facilmente). Con il parametro language puoi richiedere una lingua specifica dei sottotitoli.

Il piano gratuito include 300 crediti al mese (una trascrizione YouTube costa 5 crediti, quindi 60 video) e i piani a pagamento partono da $19/mese. Per la maggior parte dei prodotti costa meno della banda dei proxy residenziali più il tempo di ingegneria per tenerli in piedi.

Quale soluzione scegliere?

Progetto personale, volumi bassi, buona dimestichezza tecnica: la Soluzione 2 (macchina residenziale) è gratuita e abbastanza affidabile.

Volumi alti con un team dedicato all'infrastruttura: la Soluzione 1 (proxy residenziali a rotazione) offre il massimo controllo — metti a budget i costi dei proxy e la manutenzione continua.

App in produzione, agente o pipeline RAG in cui le trascrizioni sono una funzionalità e non il tuo core business: la Soluzione 4 (API hosted) — una chiamata HTTP e basta gatto col topo. In ogni caso, aggiungi sopra la Soluzione 3 (cache e backoff).