Come ottenere la trascrizione di YouTube con un'API (curl, Python, JavaScript)

Per ottenere la trascrizione di YouTube con un'API, invia una richiesta HTTP con l'URL o l'ID del video e una chiave API, poi leggi la trascrizione dalla risposta. Questa guida mostra la richiesta in curl, Python e JavaScript con l'API di trascrizione di sum.video, poi tratta formati, errori e costi.

Cosa restituisce l'API

L'endpoint restituisce i sottotitoli esistenti di un video YouTube pubblico, scritti dal creatore o generati automaticamente da YouTube. Non trascrive l'audio. Se un video non ha sottotitoli, ricevi un errore invece di un'ipotesi (più sotto).

Le basi:

• Endpoint: POST https://sum.video/api/v1/transcript (funziona anche GET)
• Autenticazione: la tua chiave nell'header X-API-Key, oppure Authorization: Bearer <key>
• Input: url oppure video_id
• lang facoltativo (predefinito en)
• format facoltativo: json, text oppure srt

La risposta indica anche la lingua reale della traccia dei sottotitoli e se è generata automaticamente, così sai che qualità aspettarti.

Passo 1: Crea una chiave API

Accedi e crea una chiave nella dashboard dell'API (/dashboard/api su sum.video). Puoi avere fino a 5 chiavi attive, utile per separare una chiave di test da una di produzione. La tua prima chiave include 10 crediti gratuiti, abbastanza per 5 trascrizioni, così puoi provare tutto quanto segue senza costi.

Passo 2: Fai la prima richiesta

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

Poiché funziona anche GET, puoi provare da uno script che si limita a costruire URL. Meglio passare la chiave nell'header, così non finisce nei log.

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript (Node 18+ o browser)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

Tieni la chiave su un server. Una chiave nel codice del browser può essere copiata da chiunque apra gli strumenti per sviluppatori.

Passo 3: Scegli il formato giusto

Se vuoi creare link a un momento del video, usa json e costruisci il link dall'offset del segmento. Per alimentare un LLM, text è più piccolo e semplice. Se in seguito vuoi cercare a mano dentro una trascrizione, vedi come cercare nella trascrizione di un video YouTube.

Passo 4: Scegli una lingua

lang è en per impostazione predefinita. Impostalo sulla lingua che vuoi, per esempio de o es. La risposta indica la lingua della traccia effettivamente restituita, quindi controllala invece di darla per scontata. Un video ha spesso una sola traccia di sottotitoli, e l'API restituisce sottotitoli reali, quindi non li traduce per te.

Passo 5: Gestisci gli errori

Prevedi questi casi fin dal primo giorno:

• 404 no_transcript: il video non ha sottotitoli, oppure è una diretta, un video privato o rimosso. Non c'è nulla da riprovare. Saltalo, oppure chiedi all'utente un altro video.
• 402 budget_exceeded: hai raggiunto il limite mensile di crediti che hai configurato. Vedi la sezione successiva.
• Limite di frequenza: ogni chiave consente 60 richieste al minuto. Distanzia i lavori in batch e rallenta quando vieni limitato.
• Errori dal nostro lato: riprova dopo una breve pausa. Non costano nulla.

Un semplice ciclo che riprova sugli errori del server e salta i 404 copre la maggior parte delle esigenze di produzione.

Quanto costa

Ogni trascrizione costa 2 crediti. Le richieste che non restituiscono una trascrizione, o che falliscono dal lato di sum.video, non costano nulla, quindi un 404 non svuota mai il tuo saldo. Puoi controllare il saldo con GET /api/v1/credits.

I crediti si vendono in pacchetti una tantum che non scadono mai:

Gli abbonati Pro ricevono anche 100 crediti bonus ogni mese. Per carichi più pesanti, come l'acquisizione di un intero canale, leggi lo scenario trascrizioni YouTube per un'app RAG su larga scala, che tratta ricarica automatica e budget. Vedi anche i prezzi.

Limiti da conoscere prima di costruire

• Funzionano solo i video con sottotitoli. È il motivo principale del 404 no_transcript.
• I sottotitoli generati automaticamente possono contenere errori, soprattutto con nomi, accenti e termini tecnici.
• L'API restituisce solo la trascrizione. Non riassume. Se vuoi riassunti, timestamp e chat sopra una trascrizione, ci pensa il riassuntore di YouTube, e lo strumento di trascrizione è la versione senza codice per un singolo video.
• La YouTube Data API ufficiale qui non è un sostituto. Il suo metodo di download dei sottotitoli richiede il permesso di modificare il video, quindi è pensato per i tuoi video (documentazione Google).

Fonti

• YouTube Data API: Captions.download
• API di trascrizione di sum.video