Trascrizioni con la YouTube Data API: perché captions.download fallisce

Se stai cercando di ottenere trascrizioni tramite la YouTube Data API, probabilmente hai già sbattuto contro il muro: captions.list restituisce allegramente gli ID delle tracce di sottotitoli per qualsiasi video, ma nel momento in cui chiami captions.download su una di esse, ottieni un 403. Ricontrolli la chiave API, aggiungi lo scope youtube.force-ssl, provi con OAuth — ancora 403. Non è un bug e non è un problema di quota. È così per design, e la documentazione seppellisce l'informazione chiave.

La restrizione, con precisione

captions.download richiede un token OAuth di un account che possiede il video. Non un account autenticato qualsiasi — il proprietario del canale (o un content manager con i relativi diritti). Gli endpoint delle captions esistono perché i creator possano gestire le tracce di sottotitoli sui propri upload: caricare un .srt, correggere un refuso, eliminare una cattiva traduzione automatica. Scaricare i sottotitoli da video arbitrari di terzi non ha mai fatto parte del contratto.

Il messaggio di errore lo dice chiaramente, una volta letto con attenzione:

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

Quindi il classico percorso di escalation — chiave API → OAuth come te stesso → scope più ampi → service account — non porta da nessuna parte. Ogni gradino fallisce lo stesso controllo di proprietà. Ci ho bruciato un pomeriggio prima di accettarlo e, a giudicare dal traffico su Stack Overflow, lo stesso vale per mezza internet.

A cosa serve ancora captions.list

Per essere onesti con la Data API: captions.list funziona con una semplice chiave API e costa circa 50 unità di quota. Ti dice quali tracce esistono, in che lingua sono e se sono generate automaticamente (trackKind: "asr") o caricate da umani. È genuinamente utile come controllo preliminare — se un video non ha alcuna traccia, sai in anticipo che ti servirà lo speech-to-text invece dell'estrazione dei sottotitoli. La Data API resta anche lo strumento giusto per ricerca, enumerazione delle playlist e metadati. Semplicemente non ti consegnerà il testo della trascrizione.

Opzione 1: recuperare i sottotitoli come fa il player

Il player video, ovviamente, riceve i dati dei sottotitoli senza il token OAuth del proprietario, e librerie come youtube-transcript-api (Python) li recuperano allo stesso modo. Sul tuo laptop funziona bene e sono tre righe di codice.

Il problema emerge in produzione: YouTube contesta in modo aggressivo le richieste provenienti dai range IP dei datacenter. Distribuisci le stesse tre righe su AWS, GCP o Heroku e inizierai a vedere "Sign in to confirm you're not a bot" ed errori IpBlocked. Ho descritto separatamente quella modalità di fallimento e i workaround in perché youtube-transcript-api viene bloccata nel cloud — versione breve: si risolve con proxy residenziali, ma è un progetto a sé.

Opzione 2: una API di trascrizione hosted

Se vuoi solo il testo a partire da un URL, un endpoint hosted evita entrambi i problemi — nessun requisito di proprietà, nessun proxy da babysitterare. youtube2text.org esegue il recupero dei sottotitoli lato server dietro proxy residenziali a rotazione, quindi la tua richiesta può arrivare da dove vuole:

# 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"

La risposta è JSON semplice:

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

Se il video semplicemente non ha sottotitoli, ottieni TRANSCRIPT_UNAVAILABLE con un 404 — la stessa situazione che captions.list avrebbe mostrato come elenco di tracce vuoto, solo rilevata in una chiamata invece di due.

C'è una guida più estesa con la gestione degli errori in estrarre le trascrizioni di YouTube con curl, e una versione Python nella guida alla migrazione da youtube-transcript-api se il codice basato su requests è più nelle tue corde.

Una configurazione combinata sensata

Cosa costruirei davvero oggi, dopo aver combattuto su entrambi i fronti:

• Data API per la discovery — ricerca, upload dei canali, playlist, date di pubblicazione. È affidabile e ha una quota generosa per i metadati.
• Un endpoint di trascrizione (hosted, o scraping in proprio con proxy se la cosa ti diverte) per il testo vero e proprio.
• Speech-to-text come fallback solo per i video del tutto privi di sottotitoli.

Cercare di forzare captions.download a fare il lavoro di mezzo è l'unica strada che categoricamente non può funzionare per video che non possiedi — nessuno scope, chiave o impostazione della console lo cambia.

Se vuoi una chiave tua invece di quella demo condivisa, l'accesso è solo con Google su youtube2text.org/app/keys — niente numero di telefono, niente carta. Il piano gratuito è di 5 video al mese; i piani a pagamento partono da 5,99 $ per 50.