Scaricare a mano una singola trascrizione di YouTube è facile. Creare un flusso di lavoro affidabile per centinaia o migliaia di video pubblici è un problema diverso: i video possono non avere sottotitoli, la lingua richiesta può non essere disponibile, il testo generato automaticamente può contenere errori e ogni risultato deve restare collegato alla sua fonte.
Questa guida mostra come recuperare il testo disponibile delle trascrizioni pubbliche di YouTube con la YouTube Transcripts API di SocQ, elaborare più URL di video tramite un’attività asincrona e preparare i risultati normalizzati per ricerca, riassunti, ricerca documentale o retrieval-augmented generation.
Risposta rapida: invia gli URL dei video pubblici di YouTube e una lingua BCP-47 facoltativa a
POST /v1/youtube/transcripts. Salva iltask_idrestituito, interroga l’endpoint dell’attività e leggi i record completati dadata.results.items. SocQ restituisce il testo semplice della trascrizione e il contesto del video quando sono disponibili sottotitoli pubblici utilizzabili. Non genera nuovo speech-to-text quando i sottotitoli mancano.
L’API ufficiale di YouTube può scaricare qualsiasi trascrizione pubblica?
No. La YouTube Data API ufficiale ha risorse per i sottotitoli, ma il suo metodo di download è pensato per le tracce di sottotitoli che l’utente autenticato può gestire. La documentazione attuale di Google dice che captions.download richiede l’autorizzazione OAuth e che l’utente deve avere il permesso di modificare il video. Il metodo costa inoltre 200 unità di quota per chiamata.
Funziona quando possiedi o gestisci il canale. Non offre un modo generale per scaricare il testo dei sottotitoli di video pubblici arbitrari. Per i requisiti di autorizzazione consulta la documentazione ufficiale di Google sul download dei sottotitoli.
Conviene distinguere tre casi d’uso:
| Requisito | Approccio adatto |
|---|---|
| Gestire i sottotitoli dei video che possiedi | YouTube Data API con OAuth |
| Recuperare il testo dei sottotitoli già disponibili da video pubblici selezionati | Un endpoint gestito per le trascrizioni come SocQ |
| Trascrivere l’audio quando non esistono sottotitoli | Una pipeline separata di speech-to-text o ASR |
SocQ copre il secondo caso. Recupera il testo disponibile delle trascrizioni; non sostiene che ogni video pubblico abbia una trascrizione e non sostituisce di nascosto il testo con un ASR generato al momento.
Invia una richiesta di trascrizione di YouTube
L’endpoint accetta uno o più URL di video pubblici. Puoi inviare anche una lingua preferita come en o zh-CN.
curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.youtube.com/watch?v=arj7oStGLkU"
],
"language": "en"
}'
L’invio avvia un’attività asincrona. Salva il task_id restituito; non inviare di nuovo lo stesso batch solo perché l’elaborazione non è immediata.
Interroga l’attività finché non raggiunge uno stato terminale:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued e running sono normali stati intermedi. Quando l’attività ha successo, leggi data.results.items. Se la pagina dei risultati riporta has_more: true, richiedi la pagina successiva con il next_cursor restituito.
Capire la risposta con la trascrizione
Un record di trascrizione normalizzato ha una forma stabile che si può salvare senza analizzare una pagina di YouTube:
{
"id": "arj7oStGLkU",
"platform": "youtube",
"resource": "transcripts",
"type": "transcript",
"url": "https://www.youtube.com/watch?v=arj7oStGLkU",
"title": "Inside the Mind of a Master Procrastinator",
"text": "A plain-text transcript snapshot.",
"language": "en",
"available_languages": ["en"],
"format": "plaintext",
"transcript_source": "auto_generated",
"author": {
"id": "UCAuUUnT6oDeKwE6v1NGQxug",
"username": "TED",
"name": "TED",
"url": "https://www.youtube.com/@TED"
},
"created_at": "2016-04-06T00:00:00",
"collected_at": "2026-07-16T08:00:00Z",
"extra": {
"duration_seconds": 843
}
}
I campi che contano di più a valle sono:
text: la trascrizione selezionata in testo semplice.language: la lingua effettivamente restituita, che può differire dalla preferenza.available_languages: le lingue di trascrizione non vuote trovate per il video.transcript_source: la classificazione della fonte dei sottotitoli, quando nota.id,url,titleeauthor: il contesto della fonte per la tracciabilità.created_atecollected_at: i momenti di pubblicazione e di raccolta.extra.duration_seconds: utile per i controlli di qualità e per stimare il carico di lavoro.
La risposta è volutamente in testo semplice. Non contiene timestamp affidabili dei segmenti né etichette dei parlanti. Non inventare orari precisi per le citazioni e non convertire la risposta in SRT come se i dati dei timestamp esistessero.
Recuperare le trascrizioni nella lingua giusta
La lingua della richiesta è una preferenza, non una garanzia. Un flusso di lavoro in produzione dovrebbe sempre smistare in base al valore di language restituito.
Per esempio, se richiedi en:
- Può essere selezionata una traccia in inglese.
- Può essere selezionata una traccia compatibile nella lingua di base.
- Può essere restituita un’altra traccia disponibile come alternativa di riserva.
- Può non essere prodotto alcun record se non esiste una trascrizione pubblica utilizzabile.
Salva language e available_languages con ogni trascrizione. Se la copertura esatta della lingua è obbligatoria, scarta o fai verificare i risultati con alternativa di riserva invece di passarli direttamente a traduzione, ricerca o a un LLM.
Conserva anche transcript_source. I sottotitoli generati automaticamente possono essere preziosi su larga scala, ma YouTube segnala che audio scadente, lingue non supportate, lunghi silenzi, parlanti sovrapposti e più lingue possono impedire i sottotitoli automatici o ridurne la qualità. Consulta le indicazioni di YouTube sulla risoluzione dei problemi dei sottotitoli automatici.
Elaborare in blocco le trascrizioni di YouTube
L’elaborazione in blocco va progettata come una pipeline di dati, non come un ciclo che presume che ogni URL abbia successo.
Video URLs
↓
Validate and deduplicate
↓
Submit transcript batches
↓
Persist task IDs
↓
Poll with backoff
↓
Read every result page
↓
Validate language and source
↓
Store, chunk, index, or export
Segui queste pratiche:
- Normalizza gli URL prima dell’invio. Riconduci gli URL di visualizzazione, di condivisione e incorporati duplicati allo stesso ID video.
- Mantieni i batch recuperabili. Salva ogni batch, i suoi URL di input, l’ID attività, il momento dell’invio e lo stato terminale.
- Interroga con backoff. Evita un ciclo di polling serrato. Aumenta il ritardo finché l’attività resta in coda o in esecuzione.
- Considera normale un output parziale. Un’attività riuscita può contenere meno record degli URL inviati perché alcuni video non hanno sottotitoli utilizzabili.
- Pagina fino alla fine. Continua finché
has_moreè false. - Rendi le scritture idempotenti. Fai l’upsert per ID video più lingua della trascrizione, così i nuovi tentativi non creano duplicati.
- Registra il momento della raccolta. Una trascrizione è un’istantanea; i sottotitoli possono essere modificati o rimossi in seguito.
Ecco un modello minimo di polling in Node.js:
const headers = {
Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
"Content-Type": "application/json"
};
const submitted = await fetch(
"https://api.socq.ai/v1/youtube/transcripts",
{
method: "POST",
headers,
body: JSON.stringify({
urls: [
"https://www.youtube.com/watch?v=arj7oStGLkU",
"https://www.youtube.com/watch?v=dQw4w9WgXcQ"
],
language: "en"
})
}
).then(response => response.json());
let task;
do {
await new Promise(resolve => setTimeout(resolve, 3000));
task = await fetch(
`https://api.socq.ai/v1/tasks/${submitted.task_id}?limit=50`,
{ headers }
).then(response => response.json());
} while (["queued", "running"].includes(task.data.status));
if (task.data.status !== "succeeded") {
throw new Error(`Transcript task ended with ${task.data.status}`);
}
const transcripts = task.data.results.items;
Prima dell’uso in produzione, aggiungi controlli sugli stati HTTP, nuovi tentativi limitati, paginazione a cursore, log strutturati e annullamento.
Gestire sottotitoli mancanti e risultati parziali
Un risultato mancante non significa automaticamente che l’intero batch sia fallito. Le cause più comuni sono:
- Il creator non ha fornito sottotitoli e quelli automatici non sono disponibili.
- I sottotitoli sono ancora in elaborazione per un video pubblicato da poco.
- La lingua parlata non è supportata o non è stata riconosciuta.
- La qualità dell’audio è scadente, il parlato si sovrappone o il video contiene più lingue.
- Il video è privato, eliminato, con restrizioni o non disponibile nell’ambiente di raccolta.
- La lingua richiesta è assente e non è disponibile alcuna alternativa di riserva utilizzabile.
Classifica gli errori invece di riprovare all’infinito:
| Tipo di errore | Azione consigliata |
|---|---|
| Nessun sottotitolo utilizzabile | Segna come non disponibile; se vuoi, indirizza a un flusso ASR separato |
| Lingua richiesta mancante | Controlla available_languages o accetta un’alternativa di riserva controllata |
| Errore temporaneo dell’attività o di rete | Riprova con backoff esponenziale e un limite |
| Video privato, eliminato o con restrizioni | Smetti di riprovare e registra il motivo |
| Trascrizione vuota o sospetta | Metti in quarantena per la validazione |
Non presentare l’output ASR come sottotitoli di YouTube senza indicarne la fonte. La distinzione conta per le verifiche di accuratezza e per le citazioni.
Esportare in sicurezza i dati delle trascrizioni
I risultati in testo semplice si possono esportare in TXT, JSON o CSV.
Per il TXT, scrivi il campo text e conserva un record di metadati a parte. Per il JSON, mantieni l’oggetto normalizzato completo. Per il CSV, usa una riga per video con campi come id, url, title, language, transcript_source, text e collected_at.
SRT e VTT richiedono segmenti temporizzati. Poiché l’endpoint delle trascrizioni di SocQ restituisce testo semplice e non segmenti, da questa sola risposta non si può produrre un’esportazione fedele di sottotitoli temporizzati.
Per gli archivi ricercabili, non salvare solo il corpo della trascrizione. Conserva ID del video, URL canonico, titolo, canale, lingua, fonte, momento di pubblicazione e momento di raccolta in ogni record derivato.
Preparare le trascrizioni per ricerca e RAG
Le trascrizioni grezze sono di solito troppo grandi e rumorose per essere inviate a un modello come un unico blocco. Un flusso migliore è:
- Normalizza gli spazi senza riscrivere la fonte.
- Rileva i testi inaspettatamente brevi o vuoti.
- Dividi il testo in chunk semantici sovrapposti.
- Associa i metadati della fonte a ogni chunk.
- Crea gli embedding.
- Salva i chunk in un indice di ricerca o vettoriale.
- Restituisci l’URL del video e i metadati della trascrizione con ogni risposta.
Un record di chunk utile ha questo aspetto:
{
"video_id": "arj7oStGLkU",
"video_url": "https://www.youtube.com/watch?v=arj7oStGLkU",
"title": "Inside the Mind of a Master Procrastinator",
"language": "en",
"transcript_source": "auto_generated",
"chunk_index": 12,
"text": "The transcript text for this chunk...",
"collected_at": "2026-07-16T08:00:00Z"
}
Poiché la risposta della fonte non ha timestamp dei segmenti, cita il video invece di dichiarare un intervallo di tempo esatto. Se le citazioni a livello di tempo sono essenziali, scegli una fonte che fornisca segmenti verificati oppure aggiungi un passaggio separato di allineamento.
Scegliere la YouTube API giusta prima di recuperare le trascrizioni
La raccolta delle trascrizioni è spesso l’ultimo passaggio di un flusso di scoperta più ampio:
- Usa YouTube Search API per trovare i video pubblici pertinenti e filtrare per disponibilità dei sottotitoli.
- Usa YouTube Videos API per i metadati normalizzati dei video.
- Usa YouTube Channel Videos API per creare l’inventario di un canale selezionato.
- Usa YouTube Transcripts API solo per i video di cui ti serve davvero il testo.
Così riduci le richieste di trascrizione non necessarie e mantieni il dataset finale legato a criteri di scoperta espliciti.
Mantenere aggiornato un dataset di trascrizioni
Un archivio di trascrizioni dovrebbe avere una policy di aggiornamento esplicita. I sottotitoli possono essere corretti dopo la pubblicazione, possono comparire nuove tracce linguistiche e un video prima disponibile può essere rimosso o limitato. Recuperare tutto ogni giorno è uno spreco, ma considerare permanente la prima risposta può lasciare in un indice di ricerca testo obsoleto o non tracciabile.
Scegli un intervallo di aggiornamento in base al caso d’uso:
- Per un dataset di ricerca una tantum, salva il momento della raccolta ed evita aggiornamenti automatici a meno che l’analisi non li richieda.
- Per un archivio di canale ricercabile, riesamina più spesso i video recenti perché i sottotitoli vengono spesso modificati poco dopo la pubblicazione.
- Per i flussi di conformità o di citazione, riconvalida la fonte prima di pubblicare una citazione o di prendere una decisione ad alto rischio.
- Per i sistemi RAG di lunga durata, conserva un hash del contenuto in modo che una trascrizione invariata non attivi inutili lavori di nuovo chunking ed embedding.
Quando una trascrizione aggiornata cambia, crea una nuova versione o conserva un record di audit invece di sovrascrivere in silenzio l’unica copia. Come minimo, salva ID del video, lingua della trascrizione, fonte dei sottotitoli, momento della raccolta, hash del testo e versione della pipeline. Se un video smette di produrre un risultato, segna il record esistente come non disponibile all’ultimo controllo; non dare per scontato che la trascrizione storica sia sempre stata non valida.
Checklist per la produzione
Prima di eseguire un lavoro ad alto volume, verifica che:
- Gli input siano URL di video pubblici di YouTube.
- Gli URL siano stati normalizzati e deduplicati.
- ID delle attività e input originali siano salvati.
- Il polling usi un ritardo e nuovi tentativi limitati.
- La paginazione a cursore prosegua finché
has_moreè false. - I risultati mancanti siano trattati separatamente dagli errori delle attività.
- La lingua restituita sia validata.
- I sottotitoli generati automaticamente siano etichettati.
- Ogni chunk o esportazione conservi i metadati della fonte.
- Il tuo uso dei contenuti rispetti i diritti applicabili, le aspettative di privacy e i termini della piattaforma.
Domande frequenti (FAQ)
Esiste una YouTube Transcript API ufficiale?
YouTube ha una Captions API ufficiale, ma scaricare una traccia di sottotitoli richiede OAuth e il permesso di modificare il video. Non è un’API generale per le trascrizioni di video pubblici arbitrari.
Posso scaricare la trascrizione di un video di YouTube senza OAuth?
La YouTube Transcripts API di SocQ usa una chiave API di SocQ e non un’autorizzazione OAuth di YouTube. Recupera il testo disponibile delle trascrizioni da URL di video pubblici selezionati.
SocQ può generare una trascrizione quando un video non ha sottotitoli?
No. L’endpoint restituisce il testo disponibile delle trascrizioni pubbliche. Un video senza sottotitoli utilizzabili può non produrre alcun risultato. Se ti serve un’alternativa di riserva con ASR, usa un flusso di speech-to-text separato e dichiarato.
Posso richiedere una lingua specifica?
Sì. Puoi inviare una lingua BCP-47 facoltativa come en o zh-CN, ma la lingua effettivamente restituita può essere diversa. Controlla sempre language e available_languages.
La risposta include timestamp ed etichette dei parlanti?
No. Il formato della risposta è testo semplice normalizzato e non fornisce timestamp dei segmenti né etichette dei parlanti garantite.
Posso recuperare più trascrizioni con una sola richiesta?
Sì. Invia più URL di video pubblici in urls, salva l’ID attività e leggi ogni pagina di risultati completata dopo che l’attività asincrona ha avuto successo.
Quanto costa la YouTube Transcripts API?
La documentazione attuale dell’endpoint indica 0,5 crediti per ogni risultato di trascrizione normalizzato. Controlla la pagina dell’endpoint prima di stimare un carico di lavoro in produzione, perché i prezzi possono cambiare.
YOUTUBE API
Prova il flusso di lavoro con un URL pubblico di YouTube
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di YouTube