Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'API di trascrizione offline

Lezione 4 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. L’endpoint di trascrizione
  2. Parametri della chiamata
  3. Formati audio supportati
  4. Struttura della risposta
  5. Combinazioni di parametri
  6. Autenticazione
  7. Punti chiave

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 da voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Cambiamenti chiave: i timestamp sono solo per segmento (word restituisce 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 voci context_bias sono 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".
  • file o file_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.

FormatoCaratteristica
MP3Il più comune, buona compressione
WAVNon compresso, qualità massima
FLACCompressione senza perdita
OGGFormato aperto, buona compressione
M4A / AACFormato Apple, comune su mobile
WEBMFormato 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, language e timestamp_granularities erano 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.