# Speech to text API per i tuoi file audio e video

> Usa la speech to text API per audio e video, con timestamp e riconoscimento dei parlanti su richiesta: 95 MB per request o 2 GB a blocchi, 1 credito/min.

Canonical: https://transcript1.com/it/features/speech-to-text-api
Language: it
Last updated: 2026-10-19

Con la Speech to text API invii un file audio o video e ricevi il testo con timestamp, la lingua di ogni segmento e, se vuoi, le etichette dei parlanti. Fino a 95 MB basta una request. Per file fino a 2 GB usi il caricamento a blocchi e puoi riprenderlo se si interrompe.

- Una request per file fino a 95 MB
- Fino a 2 GB, con ripresa del caricamento
- File eliminati 24 ore dopo la fine del lavoro

## Scegli come caricare il file prima di scrivere il client

### Audio o video, senza estrarre la traccia

Accettiamo MP3, WAV, M4A, FLAC, OGG, OPUS, MP4, MOV, WebM e MKV. Il file deve contenere una traccia audio.

### Fino a 95 MB con multipart

Invia il file a POST /v1/transcriptions come multipart/form-data. È la strada più breve quando la registrazione rientra nel limite.

### File più grandi, un blocco alla volta

Apri un upload, invia i blocchi da circa 8 MiB e conferma il completamento. Il limite è 2 GB. Se perdi la connessione, riprendi dai blocchi mancanti.

### Registrazioni fino a 5 ore

La trascrizione con IA accetta registrazioni fino a 5 ore. Se la durata supera il limite, ricevi media_too_long e non paghi.

### Il file e il testo hanno tempi diversi

Eliminiamo il file caricato 24 ore dopo lo stato finale della trascrizione. Il testo resta disponibile finché non lo elimini tu.

## API di trascrizione audio con una request fino a 95 MB

Metti i byte della registrazione nel campo multipart file. Puoi aggiungere language, diarize, source e webhook_url. La [guida al caricamento diretto](https://transcript1.com/it/docs/uploads#one-shot-upload) mostra la request completa; con un [webhook](https://transcript1.com/it/features/webhook-trascrizione) ricevi una notifica quando il lavoro termina.

Se il server ha già il file su disco, multipart è un buon punto di partenza. Lascia che il client HTTP imposti il boundary. Invia il contenuto del file, non il suo percorso locale in un campo JSON. Un file vuoto o un’estensione non supportata richiedono una correzione, non una serie di tentativi identici.

Controlla separatamente dimensioni e durata. Un audio compresso può stare sotto 95 MB ma durare più di 5 ore. Un breve video ad alta risoluzione può invece essere troppo grande per multipart. Scegli il protocollo in base ai byte, poi verifica la durata.

### cURL

```
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@interview.m4a \
  -F language=auto
```

## Un’API per trascrivere video di grandi dimensioni

Per arrivare a 2 GB, apri un upload indicando nome e dimensione del file. Ricevi il piano dei blocchi e un X-Upload-Token valido per quel caricamento. La [guida al caricamento a blocchi](https://transcript1.com/it/docs/uploads#chunked-upload) descrive tutta la sequenza.

Segui il piano restituito dall’API: per ogni blocco hai indice, offset e dimensione. Leggi esattamente quell’intervallo di byte; l’ultimo blocco può essere più corto. Il token autorizza le request PUT binarie, vale 1 ora e non sostituisce la tua chiave API.

Usa una Idempotency-Key stabile quando apri l’upload. Se il token scade, ripeti la stessa prenotazione con la stessa chiave e gli stessi parametri: ricevi un token nuovo per il caricamento già aperto. Non crearne un altro a ogni interruzione.

### Apri un upload a blocchi

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Idempotency-Key: interview-2026-10-13" \
  -H "Content-Type: application/json" \
  -d '{"upload":{"filename":"interview.m4a","size":48210334,"mime_type":"audio/mp4"}}'
```

## Invia i blocchi e conferma il caricamento

Invia ogni blocco con PUT al suo URL, usando il token dell’upload. Poi conferma il completamento: transcript1 verifica i blocchi e mette in coda la trascrizione. Gli endpoint per controllo e completamento sono nella [documentazione API](https://transcript1.com/it/docs/api-reference#uploads).

Prima di riprendere, chiama GET /v1/transcriptions/:id/upload e confronta received_chunks con il piano iniziale. Invia solo ciò che manca. Reinviare un blocco lo sostituisce, ma i byte devono sempre rispettare la dimensione prevista. Un 401 può indicare un token scaduto: non devi ricreare il file.

Se ricevi 409 upload_incomplete, usa gli indici mancanti per completare l’invio. Dopo l’accodamento controlla lo stato della trascrizione o attendi il webhook. Nella tua interfaccia distingui l’avanzamento del caricamento da quello della trascrizione.

### Invia un blocco e completa l’upload

```
curl -X PUT "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/chunks/0" \
  -H "X-Upload-Token: t1u_..." \
  -H "Content-Type: application/octet-stream" \
  --data-binary @chunk-0.bin

curl -X POST "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/complete" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"
```

## Mostra cosa sta succedendo al file

awaiting_upload significa che il caricamento è aperto: la trascrizione non è ancora partita. Mostra prima i byte inviati, poi la verifica dell’upload e infine l’elaborazione. Se perdi la connessione dopo la conferma, leggi lo stato prima di inviarla di nuovo.

Ogni team può tenere aperti fino a 20 upload. Dopo 24 ore annulliamo quelli incompleti ed eliminiamo i relativi blocchi. Per i caricamenti completati, il file viene eliminato 24 ore dopo lo stato finale della trascrizione. Se la tua app offre la riproduzione futura dell’audio, conserva una copia originale.

Il trasporto del file è solo una parte dell’integrazione. La guida [da audio a testo](https://transcript1.com/it/features/da-audio-a-testo) aiuta a preparare e controllare le registrazioni. Per la ricerca, il percorso sulle [interviste](https://transcript1.com/it/use-cases/trascrivere-intervista) spiega come tenere insieme partecipanti, citazioni e riferimenti all’audio.

## Domande frequenti

### Quali formati posso caricare?

MP3, WAV, M4A, FLAC, OGG, OPUS, MP4, MOV, WebM e MKV, con una traccia audio. Un’altra estensione restituisce 422 unsupported_media.

### Quanto può essere grande il file?

Fino a 95 MB in una request multipart, oppure fino a 2 GB a blocchi. Il tuo piano può prevedere un limite inferiore. Se lo superi, ricevi 413 media_too_large.

### Per quanto tempo conservate i file?

Eliminiamo il file 24 ore dopo lo stato finale della trascrizione. Se non completi l’upload entro 24 ore, lo annulliamo ed eliminiamo i blocchi. La trascrizione resta finché non la elimini tu.

### Posso distinguere chi parla?

Sì. Imposta diarize=true per ottenere etichette come Speaker 1 e Speaker 2. I file caricati vengono sempre trascritti con IA tramite speech-to-text.

## Approfondisci

- [Riconoscimento dei parlanti](https://transcript1.com/it/features/riconoscimento-dei-parlanti)
- [Da audio a testo](https://transcript1.com/it/features/da-audio-a-testo)
- [Caricare file (documentazione)](https://transcript1.com/it/docs/uploads)
- [Da video a testo](https://transcript1.com/it/features/trascrivere-video)