Premier Appel de Transcription

Votre première transcription avec Voxtral

Assez de théorie. Dans cette leçon, vous réalisez votre premier appel complet à l’API de transcription offline : un fichier audio local part vers Voxtral Mini Transcribe V2, et vous exploitez le texte qui revient. Le code tient en quelques lignes, mais nous irons ensuite jusqu’à la version robuste, celle que vous pourriez laisser tourner sans surveillance.

Préparer l’environnement

Le SDK Mistral s’installe en une commande, et la vérification qui suit vous évitera de chercher plus tard une erreur d’import.

# Installer le SDK Mistral
pip install mistralai

# Vérifier l'installation
python -c "import mistralai; print('SDK installé')"

Vous aurez besoin d’une clé API Mistral. Créez-la sur console.mistral.ai et stockez-la dans une variable d’environnement plutôt que dans votre code :

export MISTRAL_API_KEY="votre-cle-api-ici"

Transcription d’un fichier local

Voici le code complet pour transcrire un fichier audio local :

import os
from mistralai import Mistral

# Initialiser le client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Ouvrir et transcrire le fichier audio
with open("mon_audio.mp3", "rb") as f:
    response = client.audio.transcriptions.complete(
        model="voxtral-mini-latest",
        file={"content": f, "file_name": "mon_audio.mp3"}
    )

# Afficher le résultat
print("=== Transcription ===")
print(response.text)

C’est tout. En quatre lignes de code actif, vous obtenez la transcription complète de votre fichier audio.

Reprenons ces quatre lignes une à une. Mistral(api_key=...) crée le client avec votre clé API : c’est l’objet que vous réutiliserez pour tous les appels suivants. open("mon_audio.mp3", "rb") ouvre le fichier en mode binaire, ce qui est obligatoire pour l’audio — un oubli du b produit une erreur de décodage difficile à interpréter. Le paramètre file={"content": f, "file_name": "..."} attend un dictionnaire contenant l’objet fichier et son nom ; ce nom n’est pas décoratif, il aide le serveur à détecter le format. Enfin, response.text contient la transcription complète sous forme de chaîne de caractères.

Transcription depuis une URL

Si votre fichier audio est déjà hébergé en ligne, utilisez file_url à la place de file :

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.audio.transcriptions.complete(
    model="voxtral-mini-latest",
    file_url="https://example.com/mon_audio.mp3"
)

print(response.text)

L’URL doit être publiquement accessible. Le serveur Mistral téléchargera le fichier directement, ce qui évite de faire transiter l’audio par votre machine lorsqu’il se trouve déjà dans le cloud — un gain de bande passante appréciable sur un catalogue de plusieurs centaines de fichiers.

Passer à une version robuste

Le script minimal suffit pour un essai. En production, il vous faudra gérer le fichier introuvable, le format inattendu, la clé absente et l’erreur réseau. Le script suivant fait ces vérifications avant l’appel, puis sauvegarde le résultat.

import os
import sys
from pathlib import Path
from mistralai import Mistral

def transcrire_audio(chemin_fichier: str) -> str:
    """Transcrit un fichier audio avec Voxtral Mini Transcribe V2."""

    # Vérifier que le fichier existe
    fichier = Path(chemin_fichier)
    if not fichier.exists():
        raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")

    # Vérifier l'extension
    extensions_valides = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
    if fichier.suffix.lower() not in extensions_valides:
        raise ValueError(
            f"Format non supporté : {fichier.suffix}. "
            f"Formats valides : {', '.join(extensions_valides)}"
        )

    # Vérifier la taille (limite pratique : ~200 Mo)
    taille_mo = fichier.stat().st_size / (1024 * 1024)
    if taille_mo > 200:
        print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")

    # Initialiser le client
    api_key = os.environ.get("MISTRAL_API_KEY")
    if not api_key:
        raise EnvironmentError("Variable MISTRAL_API_KEY non définie")

    client = Mistral(api_key=api_key)

    # Transcrire
    try:
        with open(chemin_fichier, "rb") as f:
            response = client.audio.transcriptions.complete(
                model="voxtral-mini-latest",
                file={"content": f, "file_name": fichier.name}
            )
        return response.text
    except Exception as e:
        raise RuntimeError(f"Erreur de transcription : {e}")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage : python transcrire.py <fichier_audio>")
        sys.exit(1)

    chemin = sys.argv[1]
    print(f"Transcription de : {chemin}")
    print("-" * 50)

    texte = transcrire_audio(chemin)
    print(texte)

    # Sauvegarder en fichier texte
    sortie = Path(chemin).stem + "_transcription.txt"
    Path(sortie).write_text(texte, encoding="utf-8")
    print(f"\nTranscription sauvegardée dans : {sortie}")

Il s’utilise depuis le terminal en lui passant le chemin du fichier :

python transcrire.py reunion_15mars.mp3

Le script vérifie le fichier, le transcrit, affiche le résultat et le sauvegarde automatiquement dans un fichier .txt portant le même nom de base. Vous avez là le squelette d’un traitement par lot : une boucle sur un répertoire, et votre archive audio devient une archive textuelle consultable.

Ce que contient la réponse

L’objet response ne se limite pas au texte. Il vous renseigne aussi sur la durée de l’audio traité et sur la langue que le modèle a reconnue — deux informations utiles pour journaliser vos traitements et détecter un fichier qui n’est pas dans la langue attendue.

# Texte complet
print(response.text)

# Durée de l'audio (en secondes)
print(f"Durée : {response.duration:.1f}s")

# Langue détectée
print(f"Langue : {response.language}")

Le meilleur moyen de prendre la mesure de la qualité du modèle reste de le tester sur votre propre voix. Enregistrez un message vocal de trente secondes à deux minutes, lancez le script ci-dessus, puis comparez mot à mot le résultat avec ce que vous avez dit : vous verrez immédiatement où se situent les rares erreurs, presque toujours sur des noms propres. Refaites ensuite l’exercice avec un fichier dans une autre langue, sans rien changer au code, pour observer la détection automatique à l’œuvre.

Points clés à retenir

• L’appel minimal nécessite 4 lignes : client, ouverture du fichier, appel API, lecture du résultat
• Deux modes d’envoi : fichier local (file) ou URL (file_url)
• Le nom de fichier dans le dictionnaire file aide à la détection du format
• En production, ajoutez la gestion d’erreurs (fichier absent, format invalide, erreur réseau)
• response.text contient toujours la transcription complète sous forme de chaîne