---
title: "API di trascrizione per video e audio"
description: "Trasforma i link di YouTube, TikTok, Instagram, LinkedIn e Twitter/X in trascrizioni con timestamp con una sola API REST: prima i sottotitoli, l'IA quando mancano."
canonical: "https://transcript.im/it/api"
markdown: "https://transcript.im/it/api.md"
---

# API di trascrizione per video e audio

Trasforma i link di YouTube, TikTok, Instagram, LinkedIn e Twitter/X in trascrizioni con timestamp con una sola API REST: prima i sottotitoli, l'IA quando mancano.

## Collegamenti

- [HTML canonico](https://transcript.im/it/api)
- [Markdown](https://transcript.im/it/api.md)


transcript.im espone come API versionata la stessa pipeline di estrazione che alimenta il prodotto. Invia un URL di video o audio e ricevi testo con timestamp, in JSON o testo semplice, con la piattaforma rilevata per te. I sottotitoli esistenti vengono usati per primi; quando un video non ne ha, l'IA trascrive l'audio e il risultato viene consegnato in modo asincrono.

- Un solo `url` accetta un link completo o breve e rileva YouTube, TikTok, Instagram, LinkedIn e Twitter/X; per YouTube viene riconosciuto anche un id video nudo, e `platform` con `externalId` coprono una fonte che già conosci.
- I sottotitoli vengono usati per primi; quando un video non ne ha, l'IA trascrive l'audio, e un file locale caricato passa sempre dal riconoscimento vocale.
- `format=json` restituisce segmenti con timestamp, mentre `format=text` restituisce testo semplice pronto da incollare.
- L'estrazione in batch copre elenchi di URL, playlist e canali.
- L'esportazione in batch copre txt, csv, json, srt, vtt e zip; una trascrizione salvata si scarica come txt, srt, vtt, json o md.
- Le trascrizioni salvate vivono nella libreria dell'account, e il rilevamento YouTube copre ricerca, video, canali, caricamenti, playlist e sottotitoli.
- Il contratto completo è pubblicato come documento OpenAPI.

## Cosa fa l'API di transcript.im

L'API di transcript.im trasforma un link pubblico di video o audio in una trascrizione con timestamp che il tuo prodotto può leggere, archiviare, cercare o passare a un modello. Tu invii un URL; l'API risolve la piattaforma, cerca la traccia di sottotitoli già presente del creator e restituisce il testo scritto con un timestamp su ogni riga. Quando un video non ha alcun sottotitolo, l'API non si ferma a un errore: ripiega sulla trascrizione IA dell'audio parlato, così la stessa richiesta produce comunque testo.

Proprio questo comportamento è il senso di un'API di estrazione di trascrizioni: non ti servono un downloader, uno scraper di sottotitoli e un servizio di voce-testo cuciti insieme. L'API sceglie la fonte più economica che funziona per ogni link, mantiene i timestamp allineati a ciò che è stato detto davvero e indica in quale lingua ha risposto. Una trascrizione già esistente torna subito; un video che richiede riconoscimento vocale viene affidato a un job, così una registrazione lunga non tiene mai aperta la tua richiesta.

- Una richiesta, testo reale: risolvi un link e restituisci segmenti di trascrizione con timestamp o testo semplice.
- Prima i sottotitoli, poi l'IA: usa la traccia del creator quando esiste, trascrivi l'audio quando non esiste.
- Asincrono per impostazione predefinita per l'ASR: un job id ti consente di interrogare una trascrizione lunga senza bloccare.
- Consapevole della lingua: richiedi una priorità di lingua e rileggi la lingua che l'API ha risolto.
- Indipendente dalla piattaforma: chi chiama non deve sapere dove è ospitato il video.

## Una API di trascrizione per cinque piattaforme

### YouTube

Trascrizioni per qualsiasi video pubblico di YouTube, Short o registrazione in diretta, usando prima i sottotitoli del creator e la trascrizione IA quando mancano. YouTube è anche la piattaforma con una superficie di rilevamento completa — ricerca, video, canali, caricamenti, playlist e sottotitoli — disponibile accanto alla trascrizione stessa. L'arretrato di un canale o una playlist diventa un batch di trascrizioni con timestamp, mentre un singolo link torna come testo leggibile che puoi cercare.

### TikTok

Trascrizioni per video pubblici di TikTok, con i sottotitoli usati per primi e il riconoscimento vocale come ripiego. Incolla un link video e leggi il contenuto parlato come testo pulito e con timestamp che puoi riutilizzare, tradurre o citare. La stessa chiamata copre una clip breve e un caricamento più lungo, quindi un trend, un tutorial e un video di qualcuno che parla in camera tornano tutti come testo.

### Instagram

Trascrizioni per Reel e post video pubblici di Instagram. Instagram non ha una traccia di sottotitoli da leggere, quindi l'estrazione è riconoscimento vocale asincrono: invia il link, interroga il job e raccogli il testo quando è pronto. Così un Reel diventa citabile e cercabile anche se la piattaforma non ha mai pubblicato le sue parole come testo.

### LinkedIn

Trascrizioni per post video pubblici di LinkedIn, con i sottotitoli usati per primi e il riconoscimento vocale come ripiego. Il risultato torna con timestamp, quindi un intervento, una clip di prodotto o una riunione registrata diventa testo cercabile che puoi citare e riutilizzare. Estrai l'argomentazione dalla registrazione di un webinar o trasforma l'aggiornamento di un fondatore in una bozza che puoi modificare.

### Twitter/X

Trascrizioni per post video pubblici di X. X non ha una traccia di sottotitoli da leggere, quindi l'estrazione passa dal riconoscimento vocale asincrono: invia il link, interroga il job e raccogli testo con timestamp che puoi cercare. Cita un video con precisione o archivia il suo contenuto parlato prima che il post venga modificato o rimosso.

## Come scorre una richiesta di trascrizione

Una sola chiamata porta un link o un file caricato dall'input alla trascrizione, e l'API ti dice quale percorso ha seguito.

- Invia la fonte: pubblica un `url`, passa `platform` ed `externalId` quando già li conosci, oppure carica un file come `multipart/form-data` verso lo stesso endpoint.
- Ottieni una corrispondenza di sottotitoli: quando il video porta sottotitoli in una lingua della tua lista, la trascrizione torna nella risposta.
- Gestisci una lingua mancante: quando esistono sottotitoli ma nessuno corrisponde alla tua lista, la richiesta prosegue verso la trascrizione IA e restituisce `202` con un job id; un `404` con `availableLanguages` viene restituito solo quando il riconoscimento vocale non è consentito per chi chiama.
- Forza l'ASR o ripiega su di esso: una voce `asr` esplicita, un video senza alcuna traccia di sottotitoli o un file caricato avvia un job ASR e restituisce un job id.
- Interroga o ricevi in streaming: leggi il job con `GET /v1/transcript/job/{id}` finché non riesce o fallisce, oppure iscriviti al suo stream `/events` per il progresso lato server. Una query di job restituisce `200` anche per un job fallito, quindi dirama sul campo `status`.
- Leggi il risultato: una trascrizione finita porta la lingua risolta, la durata, i segmenti con timestamp e, su richiesta, metadati come titolo, autore e data di pubblicazione.
- Ripeti in sicurezza: una trascrizione già estratta viene servita dalla cache invece di avviare un nuovo job, quindi la stessa fonte può essere richiesta di nuovo.
- Ispeziona prima: `GET /v1/transcript/info` risolve una fonte ed elenca le lingue che può servire prima che ti impegni in un'estrazione.

Poiché lo stesso endpoint serve un cache hit e una nuova estrazione, la tua integrazione non dirama in base alla fonte: invia sempre la fonte e reagisce allo stato che riceve. Una corrispondenza di sottotitoli restituisce la trascrizione direttamente, una lingua mancante prosegue verso la trascrizione IA e restituisce `202` con un job id, e una risorsa davvero assente o un ripiego non consentito restituisce `404`. Ogni percorso restituisce la stessa forma di trascrizione una volta che il testo è pronto.

## Estrazione in batch ed esportazioni

I carichi di lavoro reali raramente si fermano a un solo video, quindi l'API accetta un batch come elenco di URL, playlist o canale. Ogni batch tiene i propri totali — quanti elementi sono in attesa, quanti hanno avuto successo e quanti sono falliti — e restituisce gli elementi pagina per pagina, così un canale lungo non arriva come un unico payload enorme.

- Tre forme di batch: `POST /v1/batch` accetta un elenco di URL, una playlist o un canale, in base al corpo che invii.
- Stato indipendente: un link fallito viene contrassegnato da solo e non scarta mai il resto del batch; gli elementi falliti possono essere riprovati con `/retry`.
- Elementi paginati: leggi il batch con `GET /v1/batch/{batchId}`, poi segui il token di pagina restituito per gli elementi rimanenti.
- Progresso in tempo reale: ogni interrogazione restituisce conteggi aggiornati, così chi chiama può mostrare quanto di un'esecuzione lunga è finito.
- Esporta nel tuo formato: scarica un batch finito da `/export` come `txt`, `csv`, `json`, `srt`, `vtt` o `zip`.

Per una pipeline di sottotitoli, le esportazioni `srt` e `vtt` entrano direttamente in un editor o in un player. Per un archivio, `csv`, `json` e `zip` mantengono un'intera libreria di registrazioni cercabile come un unico corpus. I formati si allineano alle risposte della singola trascrizione, quindi un consumatore che gestisce un risultato sa già leggere un batch.

## Trascrizioni salvate nella libreria dell'account

Estrazione e archiviazione sono cose separate: una trascrizione entra a far parte della libreria dell'account quando viene salvata, e la libreria è il luogo in cui la leggi, cerchi, scarichi e rimuovi in seguito senza rieseguire l'estrazione.

- Elenca i contenuti salvati: `GET /v1/library/transcripts` scorre pagina per pagina le trascrizioni dell'account, i record dei batch e le righe dello storico dei fallimenti, con ricerca, filtri per piattaforma e lingua e ordinamento.
- Leggi un elemento: `GET /v1/library/transcripts/{platform}/{externalId}` restituisce una trascrizione salvata per piattaforma e id esterno, o per la lingua che indichi.
- Scarica: la rotta `/download` esporta una trascrizione salvata come `txt`, `srt`, `vtt`, `json` o `md`.
- Contenuti correlati: la rotta `/related` elenca altri elementi salvati dello stesso canale.
- Rimuovi: `DELETE` toglie un elemento dalla libreria senza toccare la copia di nessun altro.
- Letture limitate all'account: una richiesta alla libreria restituisce solo ciò che l'account ha salvato e non avvia mai una nuova estrazione, quindi rivedere una trascrizione salvata è una lettura, non un altro job.

## Rilevamento YouTube oltre le trascrizioni

YouTube è la piattaforma in cui l'API risponde anche alle domande attorno a una trascrizione, usando gli stessi nomi di risorsa della YouTube Data API.

- Ricerca: `GET /v1/youtube/search` trova video, canali o playlist per query e restituisce risultati paginati a cursore.
- Video: `GET /v1/youtube/videos` restituisce i dettagli di un video, inclusa la disponibilità di sottotitoli.
- Canali: `GET /v1/youtube/channels` risolve un canale per id o `@handle`.
- Caricamenti di un canale: `GET /v1/youtube/channels/{channelId}/videos` percorre i caricamenti di un canale.
- Elementi di una playlist: `GET /v1/youtube/playlists/{playlistId}/items` percorre una playlist.
- Sottotitoli: `GET /v1/youtube/captions` restituisce i metadati della traccia di sottotitoli e il testo dei sottotitoli di un video. Non avvia mai un job di riconoscimento vocale: quando segnala `requiresAsync`, chiama `POST /v1/transcript` per eseguire la trascrizione.

Il rilevamento risponde a cosa trascrivere; l'estrazione risponde a cosa è stato detto. Tenerle separate significa che puoi prima cercare ed enumerare, poi inviare solo i link scelti a una richiesta di trascrizione o batch.

## Costruita per la produzione

La superficie è piccola di proposito, e le parti che contano per un servizio sono documentate invece che indovinate.

- Una sola credenziale: autenticati con una chiave API inviata come token Bearer, oppure con `X-API-Key` da uno script o un server.
- Chiavi con scope: concedi solo gli scope di cui chi chiama ha bisogno, con `transcripts` e `batches` che coprono estrazione e lavoro in batch.
- Errori strutturati: i fallimenti di estrazione e validazione restituiscono un oggetto di errore con un `code` stabile e un `message` leggibile; le risposte di autenticazione (401) e di limite di frequenza (429) usano un corpo di errore piatto più semplice.
- Limiti utili: una richiesta limitata per frequenza restituisce `429` con `Retry-After`, e le risposte riuscite portano header `X-RateLimit-*` così un client può arretrare correttamente.
- Un contratto pubblicato: il documento OpenAPI completo sostiene l'API, quindi puoi generare un client, simulare un server o validare risposte reali rispetto allo schema.
- Un fratello per gli agenti: lo stesso account e gli stessi strumenti sono raggiungibili dal server MCP di transcript.im se chi chiama è un client IA invece di un servizio.

## Correlati

- [Documentazione API](/docs)
- [Documento OpenAPI](/docs/openapi.json)
- [Server MCP](/it/mcp)
- [Agent Skills](/it/skills)
- [Generatore di trascrizioni YouTube](/it/youtube-transcript)
- [Riassuntore di video YouTube](/it/youtube-video-summarizer)
- [Generatore di sottotitoli YouTube](/it/youtube-subtitle-generator)
- [Downloader di sottotitoli YouTube](/it/youtube-subtitle-downloader)
- [Trascrizione di canali YouTube](/it/youtube-channel-transcript)
- [Trascrizione di playlist YouTube](/it/youtube-playlist-transcript)
## Domande frequenti sull'API di trascrizione

### Cos'è l'API di transcript.im?

L'API di transcript.im è una superficie REST che trasforma un link pubblico di video o audio in una trascrizione con timestamp, usando prima i sottotitoli esistenti e la trascrizione IA quando un video non ne ha.

### Quali piattaforme supporta l'API di transcript.im?

Estrae trascrizioni da YouTube, TikTok, Instagram, LinkedIn e Twitter/X rilevando la piattaforma dal link che invii. YouTube, TikTok e LinkedIn usano prima i sottotitoli con il riconoscimento vocale come ripiego; Instagram e X non hanno traccia di sottotitoli e passano direttamente al riconoscimento vocale.

### Cosa succede quando un video non ha sottotitoli?

Quando un video non ha alcuna traccia di sottotitoli, l'API avvia un job ASR e restituisce un job id; interroghi quel job finché la trascrizione è pronta, quindi la richiesta non si blocca mai sul riconoscimento vocale.

### Posso trascrivere un file audio o video locale?

Sì. `POST /v1/transcript` accetta un corpo `multipart/form-data` con una parte `file` invece di un URL. Un file caricato va direttamente al riconoscimento vocale, quindi restituisce un job `202` — oppure un risultato `200` se termina entro il budget di attesa.

### L'API di transcript.im può restituire timestamp con il testo?

Sì. Le risposte JSON portano segmenti con timestamp e le risposte di testo possono mantenere un prefisso di timestamp per riga, così puoi tornare al momento in cui è stata detta una frase.

### Come richiedo una trascrizione in una lingua specifica?

Invia un elenco di priorità delle lingue separato da virgole, incluse le voci `asr` e `asr-<code>`. Una corrispondenza di sottotitoli viene restituita direttamente; quando esistono sottotitoli ma nessuno corrisponde all'elenco, la richiesta prosegue verso la trascrizione IA e restituisce un job `202`, e un `404` con le lingue disponibili viene restituito solo quando il riconoscimento vocale non è consentito.

### Come faccio a sapere quando una trascrizione asincrona è pronta?

Interroga `GET /v1/transcript/job/{id}` con la stessa credenziale finché non segnala successo o fallimento, oppure iscriviti a `GET /v1/transcript/job/{id}/events` per aggiornamenti lato server. Una query di job restituisce `200` anche quando il job è fallito, quindi leggi i campi `status` ed `error` invece del codice HTTP.

### L'API di transcript.im supporta l'estrazione in batch?

Sì. Un batch accetta un elenco di URL, una playlist o un canale, segue lo stato di ogni elemento e restituisce gli elementi pagina per pagina.

### Quali formati di esportazione posso scaricare?

Un batch finito si esporta come `txt`, `csv`, `json`, `srt`, `vtt` o `zip`; una singola trascrizione salvata si scarica come `txt`, `srt`, `vtt`, `json` o `md`.

### Dove vivono le trascrizioni salvate?

La libreria dell'account è il luogo in cui vivono le trascrizioni salvate e i record dei batch, sotto `/v1/library`. Espone rotte di elenco, lettura, download, correlati ed eliminazione, e le sue letture sono limitate all'account e non avviano mai una nuova estrazione.

### Cosa restituisce l'endpoint dei sottotitoli YouTube?

`GET /v1/youtube/captions` restituisce i metadati della traccia di sottotitoli di un video insieme al testo dei sottotitoli. Non avvia mai un job di riconoscimento vocale; quando segnala `requiresAsync`, chiama `POST /v1/transcript` per eseguire la trascrizione.

### Come segnala l'API di transcript.im errori e limiti di frequenza?

Gli errori di estrazione e validazione usano un oggetto con `code` e `message`; l'autenticazione restituisce un `401` piatto, e il limite di frequenza restituisce un `429` piatto con `Retry-After` più header `X-RateLimit-*` così un client può arretrare correttamente.

## Aggiungi trascrizioni al tuo prodotto

Crea una chiave API, invia un link video o un file locale e leggi la trascrizione come JSON o testo semplice.

- [Crea una chiave API](/app/account/api-keys)
- [Leggi la documentazione](/docs)