Premier Appel de Transcription

Votre première transcription avec Voxtral

Dans cette leçon, vous allez réaliser votre premier appel complet à l’API de transcription offline. Nous partirons d’un fichier audio local, l’enverrons à Voxtral Mini Transcribe V2, et exploiterons le résultat.

Prérequis

Avant de commencer, vérifiez votre environnement :

# 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 :

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.

Détail du code

1. Mistral(api_key=...) — Crée le client avec votre clé API
2. open("mon_audio.mp3", "rb") — Ouvre le fichier en mode binaire (obligatoire pour l’audio)
3. file={"content": f, "file_name": "..."} — Le SDK attend un dictionnaire avec le contenu et le nom du fichier. Le nom de fichier aide le serveur à détecter le format.
4. response.text — Contient la transcription complète sous forme de chaîne de caractères

Transcription depuis une URL

Si votre fichier audio est 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 — cela évite de transiter l’audio par votre machine si le fichier est déjà dans le cloud.

Script complet avec gestion d’erreurs

En production, vous voudrez gérer les erreurs réseau, les fichiers introuvables et les limites d’API :

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}")

Utilisation

python transcrire.py reunion_15mars.mp3

Ce script vérifie le fichier, le transcrit, affiche le résultat et le sauvegarde automatiquement dans un fichier .txt.

Analyser la réponse

L’objet response retourné par l’API contient plusieurs attributs utiles :

# 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}")

Mise en pratique

Testez avec un fichier audio de votre choix :

1. Enregistrez un court message vocal (30 secondes à 2 minutes)
2. Lancez la transcription avec le script ci-dessus
3. Comparez le résultat avec ce que vous avez dit
4. Essayez avec un fichier dans une autre langue pour voir la détection automatique

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