Vai al contenuto principale
Italiano— Scegli una lingua
Menu

La tua prima chiamata di trascrizione

Lezione 5 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. La tua prima trascrizione con Voxtral
  2. Preparare l’ambiente
  3. Trascrivere un file locale
  4. Trascrivere da un URL
  5. Passare a una versione robusta
  6. Cosa contiene la risposta
  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 rimossi 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 principali: i timestamp sono solo per segmento (word restituisce 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 input context_bias sono 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 file aiuta il rilevamento del formato
  • In produzione, aggiungi la gestione degli errori (file mancante, formato non valido, errore di rete)
  • response.text contiene sempre la trascrizione completa come stringa