La tua prima chiamata di trascrizione
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 rimossi il 30 aprile 2027) sono sostituiti negli esempi davoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3evoxtral-mini-tts-3-0. Cambiamenti principali: i timestamp sono solo per segmento (wordrestituisce un errore 400), la diarizzazione è possibile in tempo reale, le impostazioni della sessione in tempo reale sono bloccate dopo il primo chunk audio e gli inputcontext_biassono in formato libero (frasi con spazi). Fonti: Migrate from Voxtral 2 · Speech to Text.
La tua prima trascrizione con Voxtral
Basta teoria. In questa lezione, effettuerai la tua prima chiamata completa all’API di trascrizione offline: un file audio locale viene inviato a Voxtral Mini Transcribe 3 ed elabori il testo restituito. Il codice sta in poche righe, ma poi lo evolveremo verso una versione robusta adatta al funzionamento non presidiato.
Preparare l’ambiente
L’SDK di Mistral si installa con un singolo comando. Il passaggio di verifica che segue ti evita di dover cercare in seguito un errore di importazione.
# Installa l'SDK di Mistral
pip install mistralai
# Verifica l'installazione
python -c "from mistralai.client import Mistral; print('SDK installato')"
Avrai bisogno di una chiave API Mistral. Creane una su console.mistral.ai e salvala in una variabile d’ambiente invece di codificarla direttamente:
export MISTRAL_API_KEY="your-api-key-here"
Trascrivere un file locale
Ecco il codice completo per trascrivere un file audio locale:
import os
from mistralai.client import Mistral
# Inizializza il client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Apri e trascrivi il file audio
with open("mon_audio.mp3", "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "mon_audio.mp3"}
)
# Visualizza il risultato
print("=== Trascrizione ===")
print(response.text)
Tutto qui. In quattro righe di codice attivo, ottieni la trascrizione completa del tuo file audio.
Analizziamo queste quattro righe. Mistral(api_key=...) crea il client con la tua chiave API; questo è l’oggetto che riutilizzerai per tutte le chiamate successive. open("mon_audio.mp3", "rb") apre il file in modalità binaria, obbligatoria per l’audio: omettere la b causa un errore di decodifica difficile da interpretare. Il parametro file={"content": f, "file_name": "..."} si aspetta un dizionario contenente l’oggetto file e il suo nome; questo nome non è decorativo, aiuta il server a rilevare il formato. Infine, response.text contiene la trascrizione completa come stringa.
Trascrivere da un URL
Se il tuo file audio è già ospitato online, usa file_url invece di file:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/mon_audio.mp3"
)
print(response.text)
L’URL deve essere pubblicamente accessibile. Il server Mistral scaricherà il file direttamente, evitando di far transitare l’audio attraverso la tua macchina quando è già nel cloud: un risparmio significativo di banda per un catalogo di diverse centinaia di file.
Passare a una versione robusta
Lo script minimale funziona per un test. In produzione, devi gestire file mancanti, formati imprevisti, chiavi assenti ed errori di rete. Lo script seguente esegue questi controlli prima della chiamata, quindi salva il risultato.
import os
import sys
from pathlib import Path
from mistralai.client import Mistral
def transcrire_audio(chemin_fichier: str) -> str:
"""Trascrive un file audio con Voxtral Mini Transcribe 3."""
# Controlla che il file esista
fichier = Path(chemin_fichier)
if not fichier.exists():
raise FileNotFoundError(f"File non trovato: {chemin_fichier}")
# Controlla l'estensione
extensions_valides = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
if fichier.suffix.lower() not in extensions_valides:
raise ValueError(
f"Formato non supportato: {fichier.suffix}. "
f"Formati validi: {', '.join(extensions_valides)}"
)
# Controlla la dimensione (limite pratico: ~200 MB)
taille_mo = fichier.stat().st_size / (1024 * 1024)
if taille_mo > 200:
print(f"Attenzione: file voluminoso ({taille_mo:.1f} Mo)")
# Inizializza il client
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
raise EnvironmentError("Variabile MISTRAL_API_KEY non definita")
client = Mistral(api_key=api_key)
# Trascrivi
try:
with open(chemin_fichier, "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": fichier.name}
)
return response.text
except Exception as e:
raise RuntimeError(f"Errore di trascrizione: {e}")
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Uso: python transcrire.py <fichier_audio>")
sys.exit(1)
chemin = sys.argv[1]
print(f"Trascrizione di: {chemin}")
print("-" * 50)
texte = transcrire_audio(chemin)
print(texte)
# Salva nel file di testo
sortie = Path(chemin).stem + "_transcription.txt"
Path(sortie).write_text(texte, encoding="utf-8")
print(f"\nTrascrizione salvata in: {sortie}")
Eseguilo dal terminale passando il percorso del file:
python transcribe.py meeting_march15.mp3
Lo script controlla il file, lo trascrive, visualizza il risultato e lo salva automaticamente in un file .txt con lo stesso nome base. Ora hai lo scheletro per l’elaborazione batch: scorri una directory e il tuo archivio audio diventa un archivio di testo ricercabile.
Cosa contiene la risposta
L’oggetto response non si limita al testo. Fornisce anche la durata dell’audio elaborato e la lingua riconosciuta dal modello: due informazioni utili per registrare i tuoi job e rilevare file che non sono nella lingua prevista.
# Testo completo
print(response.text)
# Durata audio (in secondi)
print(f"Durata: {response.duration:.1f}s")
# Lingua rilevata
print(f"Lingua: {response.language}")
Il modo migliore per valutare la qualità del modello è testarlo con la tua voce. Registra un messaggio vocale della durata da trenta secondi a due minuti, esegui lo script sopra e confronta il risultato parola per parola con ciò che hai detto: vedrai immediatamente dove si trovano i rari errori, quasi sempre sui nomi propri. Ripeti poi l’esercizio con un file in un’altra lingua, senza cambiare il codice, per osservare il rilevamento automatico della lingua in azione.
Punti chiave
- La chiamata minimale richiede 4 righe: client, apertura file, chiamata API, lettura risultato
- Due modalità di invio: file locale (
file) o URL (file_url) - Il nome del file nel dizionario
fileaiuta il rilevamento del formato - In produzione, aggiungi la gestione degli errori (file mancante, formato non valido, errore di rete)
response.textcontiene sempre la trascrizione completa come stringa