Chiama l’API dal tuo codice
Invia il link a POST /v1/transcriptions con la tua chiave API. Puoi usare Python o qualsiasi client HTTP. Con wait=60 la connessione resta aperta fino a 60 secondi. I campi e i codici di risposta sono nella documentazione della request.
Crea la chiave nella dashboard e usala dal server o da uno script. Salva subito l’ID che ricevi. Se l’attesa finisce prima della trascrizione, il lavoro continua: controllalo con GET /v1/transcriptions/:id, senza inviare di nuovo il video.
Gestisci gli stati queued, fetching e transcribing separatamente da completed e failed. Una trascrizione ancora in corso, un errore e un testo pronto da leggere devono restare casi distinti anche nella tua app.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'Controlla transcript_source e i timestamp
La risposta indica se il testo arriva dai sottotitoli e distingue le tracce del creator da quelle automatiche. billed_minutes contiene la durata arrotondata per eccesso. Trovi gli altri campi nello schema della trascrizione.
Conserva transcript_source e caption_kind se devi documentare la provenienza del testo. I sottotitoli del creator mantengono le parole pubblicate, senza timestamp delle parole. Quelli automatici di YouTube hanno i tempi di inizio; lo speech-to-text aggiunge anche fine e confidence.
Ogni segmento ha inizio e fine in secondi: puoi collegare una citazione al video o sincronizzare testo e riproduzione. Aggiungi include=words al JSON solo se ti servono i dati delle singole parole. Il JSON qui sotto mostra la struttura della risposta, non le parole del video di esempio.
{
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"status": "completed",
"transcript_source": "youtube_captions",
"caption_kind": "auto_generated",
"language": "en",
"billed_minutes": 4,
"transcript": {
"text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
"segments": [
{ "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
]
}
}Scegli tra sottotitoli e speech-to-text
source=auto è il valore predefinito. Con source=captions chiedi solo i sottotitoli: se non sono utilizzabili, ricevi no_captions e non paghi. Con source=stt trascriviamo sempre l’audio. La guida alle sorgenti spiega anche come incidono lingua e riconoscimento dei parlanti.
Scegli captions (solo sottotitoli) quando ti serve proprio la traccia pubblicata. Scegli stt quando vuoi una nuova trascrizione dell’audio o le etichette dei parlanti. Con source=auto, diarize=true passa direttamente allo speech-to-text. La combinazione di captions e diarize=true viene rifiutata: non ignoriamo una delle due opzioni.
La traccia deve corrispondere alla lingua richiesta, oppure alla lingua originale del video quando la lingua è auto. Escludiamo le traduzioni automatiche. Nello speech-to-text, language aiuta il riconoscimento: non traduce la registrazione.
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}Gestisci gli errori senza duplicare le trascrizioni
Prima di riprovare, leggi l’errore. Un video privato, un limite di età o una diretta in corso richiedono un’altra sorgente. Con no_captions puoi decidere se accettare una trascrizione dell’audio. Se il lavoro è ancora in corso, rileggilo tramite ID. I casi da gestire sono nella guida agli errori.
Per ripetere una request di creazione dopo un problema di rete, usa Idempotency-Key. Il riuso di una trascrizione recente è un’opzione distinta e richiede lo stesso video e le stesse opzioni. Una trascrizione in cache può comunque costituire un nuovo lavoro a pagamento; rileggere un lavoro già completato non consuma minuti.
Lo stesso endpoint accetta anche TikTok, Instagram e gli altri link supportati. YouTube, X, TikTok e Bluesky sono tra le piattaforme con sottotitoli utilizzabili prima dello speech-to-text. Controlla la tabella delle sorgenti prima di proporre opzioni nella tua app.