Estrarre le trascrizioni di YouTube con curl in 30 secondi

Terminale che scarica una trascrizione YouTube come testo

Non serve un account, un SDK né un browser headless per trasformare un video YouTube in testo semplice. youtube2text.org è una API REST: una chiamata per ottenere la chiave, una chiamata per ottenere la trascrizione.

Passo 1: ottieni la chiave demo gratuita

curl -s https://youtube2text.org/api/demo-key

Risposta:

{"success": true, "apiKey": "yt_..."}

La chiave demo è condivisa e limitata per IP (5 video al mese per IP) — perfetta per fare qualche prova o per script occasionali.

Passo 2: ottieni una trascrizione

curl -s "https://youtube2text.org/api/transcribe?url=https://www.youtube.com/watch?v=VIDEO_ID&maxChars=5000" \
  -H "x-api-key: yt_YOUR_KEY"

Risposta in caso di successo:

{"result": {"videoId": "...", "title": "...", "pubDate": "2025-01-01T00:00:00-07:00",
            "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

Tutto qui. Qualche dettaglio utile da conoscere:

url accetta qualsiasi formato YouTube — watch?v=, youtu.be, embed o un semplice id video di 11 caratteri.
maxChars tronca la trascrizione (valore predefinito e massimo: 150000). Comodo quando passi il testo a un LLM con un budget di token.
Authorization: Bearer <key> funziona in alternativa a x-api-key.
Preferisci POST? Invia JSON: {"url": "...", "maxChars": 5000} allo stesso endpoint.

Gestione degli errori

Ogni errore arriva sempre nello stesso formato leggibile dalle macchine:

{"error": {"code": "RATE_LIMIT_EXCEEDED", "message": "...", "status": 429,
           "docsUrl": "https://youtube2text.org/api.md", "retryAfterSeconds": 3600}}

I codici che incontrerai davvero:

TRANSCRIPT_UNAVAILABLE — il video non ha alcun sottotitolo.
RATE_LIMIT_EXCEEDED — quota esaurita; retryAfterSeconds indica quando riprovare.
UNAUTHORIZED — chiave mancante o non valida; recuperane una da /api/demo-key.

Quando la chiave demo non basta

Accedi con Google su youtube2text.org/app/keys e crea la tua chiave personale: anche l'account gratuito include 5 video al mese, mentre i piani a pagamento vanno da 50 al mese fino a illimitato.

Il riferimento completo leggibile dalle macchine — parametri, tutti i codici di errore, integrazione MCP — si trova su youtube2text.org/api.md. Se stai collegando tutto questo a un agente AI invece che a uno script shell, leggi poi la guida MCP.