Endpoint API

Usa https://api.transcript1.com/v1 come URL di base per le chiamate API.

• Invia e ricevi body JSON. I nomi dei campi usano snake_case.
• Le date seguono ISO 8601 in UTC, ad esempio 2026-10-13T09:30:00.000Z.
• Durata e tempi della trascrizione sono espressi in secondi.
• Per interpretare gli errori, fai riferimento alla struttura comune.
• Nelle risposte alle chiamate autenticate trovi sempre X-RateLimit-Limit e X-RateLimit-Remaining. I dettagli sono in Costi e limiti.
• Con source=auto cerchiamo prima sottotitoli adatti nella lingua originale su YouTube, X, TikTok, Bluesky, Dailymotion e LinkedIn. Se non possiamo usarli, passiamo allo speech-to-text. Non tutti i video hanno sottotitoli. Con source=captions attivi la modalità captions (solo sottotitoli): non scarichiamo audio e non avviamo STT. Senza una traccia adatta ricevi no_captions. Con source=stt o il riconoscimento dei parlanti, usiamo direttamente l'audio. Consulta Link e opzioni di trascrizione per le restrizioni e per sapere quando ricevi timestamp dei segmenti o delle parole.

Puoi scaricare la specifica OpenAPI per usarla nei tuoi strumenti:

• JSON
• YAML

Per autenticarti, aggiungi l'header Authorization nel formato Authorization: Bearer <token>.

• Puoi usare una chiave API, riconoscibile dal prefisso t1_. La crei in “API keys” e puoi usarla con tutti gli endpoint.
• I client MCP come Claude e ChatGPT ricevono un access token OAuth quando li colleghi. Il prefisso è t1o_ e gli scope sono transcriptions:read e transcriptions:write.

Scope	Chiamate consentite
transcriptions:read	GET /v1/transcriptions, GET /v1/transcriptions/:id, GET /v1/transcriptions/:id/upload e GET /v1/account
transcriptions:write	POST /v1/transcriptions, DELETE /v1/transcriptions/:id e POST /v1/transcriptions/:id/upload/complete

• Se al token manca lo scope necessario, l'API risponde 403 insufficient_scope.
• Se non invii una credenziale o non è valida, ricevi 401 unauthorized.

Per inviare i chunk con PUT /v1/transcriptions/:id/upload/chunks/:index, usa invece X-Upload-Token. Lo ricevi all'apertura del caricamento. Segui la procedura in Caricare file.

Quando chiami POST /v1/transcriptions, aggiungi Idempotency-Key: potrai ripetere la chiamata senza creare una seconda trascrizione.

Scegli un valore da 1 a 255 caratteri e invialo nell'header, non nella query.

• Se riusi chiave e parametri, recuperi la trascrizione della prima chiamata e non paghi di nuovo.
• Se riusi la chiave ma cambi i parametri, ricevi 409 idempotency_conflict.
• Per un caricamento in parti, ripetere la chiamata di creazione con la stessa chiave ti dà un nuovo token di caricamento.

• Se l'API rifiuta la chiamata, ricevi l'errore subito nella risposta.
• Se la chiamata viene accettata ma la trascrizione non riesce durante l'elaborazione, il suo status diventa failed.

Come leggere un errore API

Quando una chiamata /v1 non viene accettata, trovi un oggetto error con code, message e retryable.

• Nel tuo codice, distingui i casi usando code.
• Usa message per mostrare la spiegazione all'utente, senza basare la logica sul testo: può cambiare.
• Con retryable uguale a true, puoi riprovare la stessa chiamata più tardi.

In alcuni casi trovi altri campi oltre a retryable:

Campo	Codice associato	A cosa serve
action_url	insufficient_minutes	Link per acquistare un piano o aggiungere minuti con una ricarica.
minutes_needed, minutes_remaining	insufficient_minutes	Minuti necessari per la chiamata e saldo disponibile. I minuti necessari valgono null se non li conosciamo ancora.
supported_platforms	unsupported_platform	Elenco delle piattaforme accettate: ["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"].
missing_chunks	upload_incomplete	Indici delle parti del file che devi ancora inviare.
max_bytes	media_too_large	Limite di dimensione del file per il tuo account, in byte.
params	invalid_request	Negli errori di validazione del body o della query, associa ogni campo alla spiegazione del problema.

Quando l'API rifiuta la chiamata

Stato HTTP	code	Puoi riprovare senza modifiche?	Causa
400, 422	invalid_request	No	Manca un parametro o un campo del body, oppure il valore non è valido. Succede anche con diarize insieme a source: "captions", con reuse_recent insieme a webhook_url o con un body che non contiene JSON valido.
422	invalid_url	No	Il link non è valido oppure platform non corrisponde al link. Usa YouTube, X, TikTok, Instagram, Facebook, Bluesky o una delle altre piattaforme in Link e opzioni di trascrizione.
422	unsupported_platform	No	Il valore di platform non rientra tra quelli accettati.
422	unsupported_media	No	L'estensione del file non è tra quelle supportate.
401	unauthorized	No	Manca la credenziale, oppure non è valida, è scaduta o è stata revocata. Vale anche per un token di caricamento non valido o scaduto.
403	insufficient_scope	No	Il token OAuth non ha lo scope transcriptions:read o transcriptions:write necessario per la chiamata.
403	email_not_verified	No	Devi confermare l'indirizzo email prima di avviare una trascrizione.
402	insufficient_minutes	No	Hai 0 minuti utilizzabili, oppure non bastano per questa trascrizione.
402	no_active_plan	No	Per acquistare una ricarica serve un piano a pagamento attivo. Questo errore arriva dall'endpoint di fatturazione della dashboard, non dagli endpoint di trascrizione.
404	not_found	No	Nessuna trascrizione corrisponde all'ID, oppure appartiene a un altro team.
409	upload_incomplete	No	Il file non è completo: invia i chunk mancanti e richiama il completamento.
409	invalid_state	No	La trascrizione non è più in attesa del file. Non puoi inviare altri chunk né completare il caricamento.
409	idempotency_conflict	No	Hai già usato Idempotency-Key con parametri diversi.
413	media_too_large	No	La dimensione del file supera il limite del tuo account. Consulta Caricare file.
413	invalid_request	No	Il body JSON supera 1 MB. Per i file, il codice corrispondente è media_too_large.
429	rate_limited	Sì	Hai superato il numero di chiamate al minuto. Aspetta quanto indicato da Retry-After, in secondi.
429	too_many_active_jobs	Sì	Hai troppe trascrizioni in corso o troppi caricamenti aperti. Aspetta quanto indicato da Retry-After, in secondi.
500	internal_error	Sì	Si è verificato un errore nei nostri sistemi. Puoi riprovare tra poco.
503	service_unavailable	Sì	Il servizio non è disponibile al momento. Puoi riprovare tra poco.

Se il browser si autentica con un cookie di login, controlliamo anche l'origine della chiamata. Da un altro sito ricevi 403 forbidden_origin.

Il controllo non si applica alle chiamate API con l'header Authorization.

In tutte le risposte 429, l'header Retry-After indica quanti secondi aspettare. Trovi le soglie per piano in Costi e limiti.

Quando e come riprovare

• Ripeti la chiamata senza modificarla solo con retryable uguale a true: vale per rate_limited, too_many_active_jobs, internal_error e service_unavailable.
• Aspetta i secondi di Retry-After, se presente. Altrimenti aumenta l'intervallo tra i tentativi.
• Per ripetere POST /v1/transcriptions, mantieni lo stesso Idempotency-Key. Se la prima chiamata era riuscita, eviti un secondo addebito.
• Con gli altri codici, risolvi prima il problema della chiamata.

Quando la trascrizione non riesce

Se una trascrizione ha status uguale a failed, trovi il motivo nell'oggetto error, con i campi code e message.

Può succedere anche dopo la risposta alla chiamata iniziale. Controlla error quando leggi lo stato o ricevi il webhook transcription.failed.

error.code	Cosa è successo	Cosa fare
media_unavailable	Il video non esiste oppure non è più accessibile.	Non riprovare lo stesso link: controlla l'URL.
media_private	Non possiamo accedere al video perché è privato.	Usa un post pubblico o un video YouTube pubblico o non in elenco.
login_required	Per vedere il video serve il login sulla piattaforma.	Non riproviamo: è un errore permanente.
no_audio	Manca la traccia audio del video.	Non riproviamo: è un errore permanente.
age_restricted	La piattaforma applica un limite di età al video.	Non riprovare il link; carica il file.
live_stream	La diretta è in corso o deve ancora iniziare.	Aspetta che sia finita, poi riprova.
no_captions	Hai scelto source uguale a captions, ma manca una traccia di sottotitoli adatta.	Passa a source: "auto" o "stt".
media_too_long	La registrazione supera il limite di 5 ore per lo speech-to-text.	Dividila in parti più brevi prima di inviarla.
unsupported_media	Non riusciamo a leggere il file, oppure manca la traccia audio.	Invia un file in un formato supportato.
no_speech	Nessun parlato rilevato.	Non riprovare la stessa registrazione.
unsupported_language	Non supportiamo la lingua della registrazione.	Correggi language con un codice supportato oppure "auto".
insufficient_minutes	Al momento dell'addebito non avevi più abbastanza minuti.	Fai una ricarica, poi riprova.
fetch_failed	Non siamo riusciti a scaricare la registrazione dopo più tentativi.	Puoi riprovare più tardi.
transcription_failed	La trascrizione dell'audio non è riuscita dopo più tentativi.	Puoi riprovare più tardi.

Se la trascrizione non riesce o la annulli, non paghi. Se avevamo già scalato dei minuti, li restituiamo al tuo saldo.

Specifica webhook_url alla creazione per ricevere una notifica: transcript1 invia un POST firmato a quell'indirizzo quando il testo è pronto o la trascrizione non riesce.

Puoi configurare i webhook solo nell'API REST. Il server MCP non accetta un parametro per attivarli.

Scegliere l'URL che riceve le notifiche

In POST /v1/transcriptions, aggiungi webhook_url:

• Nel body JSON, se passi un link video supportato o apri un caricamento in parti.
• Nei campi del form, se carichi il file intero in una sola chiamata.

Controlla che l'URL:

• Usi HTTPS.
• Non includa nome utente o password.
• Risolva a un indirizzo pubblico.

Con indirizzi privati, di loopback, link-local o comunque non pubblici, ricevi 422 invalid_request. Verifichiamo l'indirizzo sia alla creazione della trascrizione sia a ogni invio del webhook.

Non puoi usare webhook_url insieme a reuse_recent=true.

Quali eventi ricevi

type	Quando lo inviamo
transcription.completed	Lo stato passa a completed.
transcription.failed	Lo stato passa a failed. Trovi code e message in data.error.

Se annulli una trascrizione, non inviamo webhook.

Cosa contiene la notifica

Nel body JSON trovi:

• created_at, la data di creazione dell'evento.
• data, l'oggetto trascrizione senza il campo transcript.

Per ottenere il testo, usa l'id presente in data e chiama GET /v1/transcriptions/:id.

La chiamata ha questi header:

• Content-Type: application/json
• User-Agent: transcript1-webhooks/1.0
• X-Transcript1-Signature, per verificare la firma come spiegato qui sotto.

Controllare la firma prima di usare i dati

Leggi l'header X-Transcript1-Signature, presente a ogni invio nel formato t=<unix seconds>,v1=<hex digest>.

• t indica il momento della firma, come timestamp Unix in secondi.
• Per ottenere v1, calcola l'HMAC-SHA256 di "<t>.<raw body>" e codificalo in esadecimale. Unisci il valore di t, un punto e il body esattamente come lo hai ricevuto. Come chiave usa tutto il segreto di firma, incluso whsec_.

Controlla la firma sui byte originali del body, prima del parsing JSON. Se fai il parsing e poi serializzi di nuovo, potresti cambiare spazi o ordine delle chiavi: la firma non corrisponderebbe più.

• Per confrontare le firme, usa un confronto in tempo costante.
• Scarta le chiamate con un t troppo distante dall'ora corrente. Negli esempi la tolleranza è di 5 minuti.
• In Express, acquisisci il body come testo prima di fare il parsing.
• In Flask, usa request.get_data(as_text=True) per fornire il valore di raw_body.

Gestire il segreto di firma

Ogni team ha un segreto con prefisso whsec_, usato per firmare i webhook di tutte le sue trascrizioni.

Puoi visualizzarlo o sostituirlo in “Webhooks”.

La sostituzione è immediata: da quel momento firmiamo i webhook con il nuovo segreto.

Risposte, nuovi tentativi e duplicati

• Rispondi con un codice 2xx per confermare la ricezione.
• Consideriamo il tentativo non riuscito se riceviamo un altro codice, incontriamo un errore di connessione o non otteniamo risposta entro 10 secondi.
• In quel caso riproviamo, fino a 6 tentativi totali, con backoff esponenziale: aspettiamo 2, 4, 8, 16 e 32 minuti tra un invio e l'altro. L'ultimo arriva circa un'ora dopo il primo.
• Indica direttamente l'URL finale: transcript1 non segue i redirect e considera una risposta 3xx un tentativo non riuscito.
• Lo stesso evento può arrivare più volte, ad esempio se il tuo server risponde dopo il timeout. Riconosci i duplicati dalla coppia data.id e type e ignorali.