L'API di trascrizione offline
In questa pagina
Corso aggiornato il 3 novembre 2026 per Voxtral 3, basato sulla guida Migrate from Voxtral 2 di Mistral: i modelli Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), deprecati il 31 ottobre 2026 e ritirati il 30 aprile 2027, sono sostituiti negli esempi davoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3evoxtral-mini-tts-3-0. Cambiamenti chiave: i timestamp sono solo per segmento (wordrestituisce un errore 400), la diarizzazione in tempo reale è supportata, le impostazioni della sessione in tempo reale sono bloccate dopo il primo chunk audio e le vocicontext_biassono in formato libero (frasi con spazi). Fonti: Migrate from Voxtral 2 · Speech to Text.
L’endpoint di trascrizione
L’API di trascrizione offline di Mistral utilizza l’endpoint /audio/transcriptions. Si tratta di un’API sincrona: invii un file audio, la richiesta rimane aperta durante l’elaborazione e ricevi l’intera trascrizione nella risposta. Non c’è alcun ID attività da interrogare né webhook da configurare. Questo semplifica notevolmente il tuo codice, ma devi prevedere timeout generosi per i file lunghi.
Prima di iniziare a scrivere codice, assicurati di avere tre prerequisiti: un account sulla piattaforma Mistral (console.mistral.ai), una chiave API attiva e l’SDK Python installato.
Installazione dell’SDK
pip install mistralai
Parametri della chiamata
Tutto passa attraverso client.audio.transcriptions.complete(). Due parametri sono obbligatori e quattro sono opzionali. Questi parametri opzionali sono ciò che trasforma una trascrizione grezza in un deliverable utilizzabile.
Parametri obbligatori
model— L’identificativo del modello. Per la trascrizione offline, usa"voxtral-mini-transcribe-3"(consigliato) o una versione specifica come"voxtral-mini-transcribe-3".fileofile_url— Il file audio da trascrivere. Hai due opzioni:file: Un dizionario{"content": file_object, "file_name": "name.mp3"}per il caricamento diretto.file_url: Un URL pubblico che punta al file audio.
Scegliere tra file e file_url è una decisione architetturale. Se il tuo audio è già archiviato in una posizione pubblicamente accessibile, file_url evita di far transitare il file attraverso il tuo server. Se il file proviene dal dispositivo di un utente o da un archivio privato, il caricamento diretto è necessario.
Parametri opzionali
Quattro impostazioni opzionali modificano la natura dell’output.
language si aspetta un codice lingua ISO, come "fr" o "en", e bypassa il rilevamento automatico. Impostalo forzatamente per batch omogenei, come un catalogo di interviste condotte interamente in francese, per evitare che un breve passaggio in inglese faccia cambiare modello a metà file. Nota che è incompatibile con timestamp_granularities.
timestamp_granularities accetta la lista ["segment"] e attiva la restituzione dei timestamp segmento per segmento. Con Voxtral 3, la granularità word non esiste più e restituisce un errore 400. Questo parametro abilita file di sottotitoli sincronizzati con il video o passaggi indicizzati in una conferenza di due ore.
diarize è un booleano. Quando impostato su True, il modello identifica gli interlocutori e attribuisce ogni segmento a uno di loro. Per un comitato esecutivo di sei persone, questa è la differenza tra un muro di testo anonimo e un rapporto in cui ogni impegno è attribuibile.
Infine, context_bias accetta una lista di termini—una singola parola o una frase con spazi, come un nome di prodotto—per migliorare il riconoscimento di vocaboli specifici. Il numero di voci non è più fisso, ma condividono la finestra di contesto con l’audio, quindi mantieni la lista breve. Una riunione tecnica con termini come “Kubernetes” e “GDPR” diventa significativamente più leggibile con questa impostazione.
Formati audio supportati
Voxtral accetta formati audio comuni e raramente avrai bisogno di convertire qualcosa in anticipo. In caso di dubbio, consulta la pagina Audio formats nella documentazione.
| Formato | Caratteristica |
|---|---|
| MP3 | Il più comune, buona compressione |
| WAV | Non compresso, qualità massima |
| FLAC | Compressione senza perdita |
| OGG | Formato aperto, buona compressione |
| M4A / AAC | Formato Apple, comune su mobile |
| WEBM | Formato web, comune per registrazioni browser |
Il limite critico è la finestra di contesto del modello, condivisa tra l’audio e il vocabolario context_bias. Una richiesta che supera questo limite viene rifiutata con un errore 400; l’API non tronca il file. Per file molto lunghi, come un seminario di un’intera giornata, suddividili prima dell’invio, preferibilmente nei punti di silenzio per evitare di tagliare le frasi a metà.
Struttura della risposta
La risposta contiene come minimo il testo trascritto:
response.text # Il testo trascritto completo (str)
Se hai richiesto i timestamp (timestamp_granularities), la risposta include anche:
response.segments # Lista di segmenti con start, end, text
Se hai abilitato la diarizzazione (diarize=True), ogni segmento include l’identità dell’interlocutore:
segment.speaker_id # Identificativo dell'interlocutore (str)
segment.start # Tempo di inizio in secondi (float)
segment.end # Tempo di fine in secondi (float)
segment.text # Testo del segmento (str)
In breve, la forma dell’oggetto restituito dipende dalla tua richiesta. Il codice che iterava su response.segments senza passare timestamp_granularities fallirà. Verifica sempre la coerenza tra i tuoi parametri di input e la gestione dell’output.
Combinazioni di parametri
Ecco le cinque combinazioni valide che incontrerai più spesso, dalla più semplice alla più specializzata.
# Trascrizione semplice (solo testo)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Con lingua forzata (nessun timestamp)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# Con timestamp per segmento
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Con diarizzazione + timestamp
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# Con context biasing
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Un vincolo sorprendente in Voxtral 2 era che language e timestamp_granularities non potevano essere usati insieme nella stessa chiamata. La documentazione di Voxtral 3 non menziona più questa restrizione; verificala con un test prima di farci affidamento.
Autenticazione
Tutte le richieste richiedono una chiave API valida passata al costruttore del client. In sviluppo, un argomento diretto è sufficiente. In produzione, usa una variabile d’ambiente per evitare che la chiave finisca nel tuo repository Git.
from mistralai.client import Mistral
# Tramite argomento diretto
client = Mistral(api_key="your-api-key")
# O tramite variabile d'ambiente (consigliato per la produzione)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Punti chiave
- L’endpoint
/audio/transcriptionsè sincrono: invia il file, ricevi il testo. - Due modalità di caricamento: caricamento diretto (
file) o URL pubblico (file_url). - Parametri opzionali:
language,timestamp_granularities,diarize,context_bias. - In Voxtral 2,
languageetimestamp_granularitieserano mutualmente esclusivi; la documentazione di Voxtral 3 non lo afferma più. - I formati audio comuni sono supportati; il limite è la finestra di contesto condivisa tra audio e
context_bias(errore 400 se superata). - Diarizzazione e timestamp possono essere combinati.