Votre premier appel de transcription
Pe această pagină
Cours mis à jour le 3 novembre 2026 pour Voxtral 3, basé sur le guide Migrate from Voxtral 2 de Mistral : les modèles Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), dépréciés le 31 octobre 2026 et supprimés le 30 avril 2027, sont remplacés dans les exemples parvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3etvoxtral-mini-tts-3-0. Changements clés : les horodatages sont uniquement par segment (wordrenvoie une erreur 400), la diarisation est possible en temps réel, les paramètres de session en temps réel sont verrouillés après le premier fragment audio, et les entréescontext_biassont en texte libre (phrases avec espaces). Sources : Migrate from Voxtral 2 · Speech to Text.
Votre première transcription avec Voxtral
Assez de théorie. Dans cette leçon, vous effectuerez votre premier appel complet à l’API de transcription hors ligne : un fichier audio local est envoyé à Voxtral Mini Transcribe 3, et vous traitez le texte retourné. Le code tient en quelques lignes, mais nous évoluerons ensuite vers une version robuste adaptée à une exploitation automatisée.
Préparer l’environnement
Le SDK Mistral s’installe en une seule commande. L’étape de vérification qui suit vous évite de devoir traquer une erreur d’importation plus tard.
# Installer le SDK Mistral
pip install mistralai
# Vérifier l'installation
python -c "from mistralai.client import Mistral; print('SDK installed')"
Vous aurez besoin d’une clé API Mistral. Créez-en une sur console.mistral.ai et stockez-la dans une variable d’environnement plutôt que de la coder en dur :
export MISTRAL_API_KEY="your-api-key-here"
Transcrire un fichier local
Voici le code complet pour transcrire un fichier audio local :
import os
from mistralai.client 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-transcribe-3",
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 intégrale de votre fichier audio.
Examinons ces quatre lignes. 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 : omettre le b provoque 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.
Transcrire depuis une URL
Si votre fichier audio est déjà hébergé en ligne, utilisez file_url au lieu de 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 doit être accessible publiquement. Le serveur Mistral téléchargera le fichier directement, ce qui évite de faire transiter l’audio par votre machine lorsqu’il est déjà dans le cloud : une économie de bande passante significative pour un catalogue de plusieurs centaines de fichiers.
Passer à une version robuste
Le script minimal fonctionne pour un test. En production, vous devez gérer les fichiers manquants, les formats inattendus, les clés absentes et les erreurs réseau. Le script suivant effectue ces vérifications avant l’appel, puis sauvegarde le résultat.
import os
import sys
from pathlib import Path
from mistralai.client import Mistral
def transcrire_audio(chemin_fichier: str) -> str:
"""Transcrit un fichier audio avec Voxtral Mini Transcribe 3."""
# 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-transcribe-3",
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 dans un fichier texte
sortie = Path(chemin).stem + "_transcription.txt"
Path(sortie).write_text(texte, encoding="utf-8")
print(f"\nTranscription sauvegardée dans : {sortie}")
Exécutez-le depuis le terminal en passant le chemin du fichier :
python transcribe.py meeting_march15.mp3
Le script vérifie le fichier, le transcrit, affiche le résultat et l’enregistre automatiquement dans un fichier .txt portant le même nom de base. Vous disposez désormais du squelette pour un traitement par lots : parcourez un répertoire en boucle, 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 fournit également la durée de l’audio traité et la langue reconnue par le modèle : deux informations utiles pour journaliser vos tâches et détecter les fichiers qui ne sont 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}")
La meilleure façon d’évaluer la qualité du modèle est de le tester sur votre propre voix. Enregistrez un message vocal durant trente secondes à deux minutes, exécutez le script ci-dessus et comparez le résultat mot pour mot avec ce que vous avez dit : vous verrez immédiatement où se situent les rares erreurs, presque toujours sur les noms propres. Répétez ensuite l’exercice avec un fichier dans une autre langue, sans modifier le code, pour observer la détection automatique de la langue en action.
Puncte cheie
- 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 du fichier dans le dictionnaire
fileaide à la détection du format - En production, ajoutez la gestion des erreurs (fichier manquant, format invalide, erreur réseau)
response.textcontient toujours la transcription complète sous forme de chaîne de caractères