L'API de transcription hors ligne
Šajā lapā
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 retiré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 en temps réel est prise en charge, 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.
Le point de terminaison de transcription
L’API de transcription hors ligne de Mistral utilise le point de terminaison /audio/transcriptions. Il s’agit d’une API synchrone : vous envoyez un fichier audio, la requête reste ouverte pendant le traitement et vous recevez la transcription complète dans la réponse. Il n’y a aucun identifiant de tâche à interroger ni aucun webhook à configurer. Cela simplifie considérablement votre code, mais vous devez prévoir des délais d’attente généreux pour les fichiers longs.
Avant de commencer à coder, assurez-vous de disposer de trois prérequis : un compte plateforme Mistral (console.mistral.ai), une clé API active et le SDK Python installé.
Installation du SDK
pip install mistralai
Paramètres d’appel
Tout passe par client.audio.transcriptions.complete(). Deux paramètres sont obligatoires et quatre sont optionnels. Ces paramètres optionnels sont ce qui transforme une transcription brute en un livrable exploitable.
Paramètres obligatoires
model— L’identifiant du modèle. Pour la transcription hors ligne, utilisez"voxtral-mini-transcribe-3"(recommandé) ou une version épinglée comme"voxtral-mini-transcribe-3".fileoufile_url— Le fichier audio à transcrire. Vous avez deux options :file: Un dictionnaire{"content": file_object, "file_name": "name.mp3"}pour un téléversement direct.file_url: Une URL publique pointant vers le fichier audio.
Le choix entre file et file_url est une décision d’architecture. Si votre audio est déjà stocké à un emplacement accessible publiquement, file_url évite de faire transiter le fichier par votre serveur. Si le fichier provient de l’appareil d’un utilisateur ou d’un stockage privé, le téléversement direct est nécessaire.
Paramètres optionnels
Quatre paramètres optionnels modifient la nature du résultat.
language attend un code de langue ISO, tel que "fr" ou "en", et contourne la détection automatique. Forcez ce paramètre pour des lots homogènes, comme un catalogue d’entretiens menés entièrement en français, afin d’éviter qu’un bref passage en anglais ne fasse basculer le modèle en cours de fichier. Notez qu’il est incompatible avec timestamp_granularities.
timestamp_granularities prend la liste ["segment"] et déclenche le retour des horodatages segment par segment. Avec Voxtral 3, la granularité word n’existe plus et renvoie une erreur 400. Ce paramètre permet de générer des fichiers de sous-titres synchronisés avec une vidéo ou d’indexer des passages dans une conférence de deux heures.
diarize est un booléen. Lorsqu’il est défini sur True, le modèle identifie les locuteurs et attribue chaque segment à l’un d’eux. Pour un comité de direction de six personnes, c’est la différence entre un mur de texte anonyme et un rapport où chaque engagement est attribuable.
Enfin, context_bias accepte une liste de termes — un seul mot ou une phrase avec des espaces, comme un nom de produit — pour améliorer la reconnaissance d’un vocabulaire spécifique. Le nombre d’entrées n’est plus fixe, mais elles partagent la fenêtre de contexte avec l’audio, alors gardez la liste courte. Une réunion d’ingénierie comportant des termes comme “Kubernetes” et “GDPR” devient considérablement plus lisible avec ce paramètre.
Formats audio pris en charge
Voxtral accepte les formats audio courants et vous aurez rarement besoin de convertir quoi que ce soit au préalable. En cas de doute, consultez la page Audio formats dans la documentation.
| Format | Caractéristique |
|---|---|
| MP3 | Le plus courant, bonne compression |
| WAV | Non compressé, qualité maximale |
| FLAC | Compression sans perte |
| OGG | Format ouvert, bonne compression |
| M4A / AAC | Format Apple, courant sur mobile |
| WEBM | Format web, courant pour les enregistrements navigateur |
La limite critique est la fenêtre de contexte du modèle, qui est partagée entre l’audio et le vocabulaire context_bias. Une requête dépassant cette limite est rejetée avec une erreur 400 ; l’API ne tronque pas le fichier. Pour les fichiers très longs, comme un séminaire d’une journée, découpez-les avant l’envoi, de préférence aux moments de silence pour éviter de couper des phrases en deux.
Structure de la réponse
La réponse contient au minimum le texte transcrit :
response.text # Le texte transcrit complet (str)
Si vous avez demandé des horodatages (timestamp_granularities), la réponse inclut également :
response.segments # Liste de segments avec début, fin, texte
Si vous avez activé la diarisation (diarize=True), chaque segment inclut l’identité du locuteur :
segment.speaker_id # Identifiant du locuteur (str)
segment.start # Heure de début en secondes (float)
segment.end # Heure de fin en secondes (float)
segment.text # Texte du segment (str)
En bref, la forme de l’objet retourné dépend de votre requête. Un code qui itère sur response.segments sans passer timestamp_granularities échouera. Vérifiez toujours la cohérence entre vos paramètres d’entrée et votre gestion de la sortie.
Combinaisons de paramètres
Voici les cinq combinaisons valides que vous rencontrerez le plus souvent, de la plus simple à la plus spécialisée.
# Transcription simple (texte uniquement)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Avec langue forcée (pas d'horodatages)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# Avec horodatages par segment
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Avec diarisation + horodatages
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# Avec biais de contexte
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Une contrainte surprenante dans Voxtral 2 était que language et timestamp_granularities ne pouvaient pas être utilisés ensemble dans le même appel. La documentation de Voxtral 3 ne mentionne plus cette restriction ; vérifiez cela par un test avant de vous y fier.
Authentification
Toutes les requêtes nécessitent une clé API valide passée au constructeur du client. En développement, un argument direct suffit. En production, utilisez une variable d’environnement pour éviter que la clé ne se retrouve dans votre dépôt Git.
from mistralai.client import Mistral
# Via un argument direct
client = Mistral(api_key="your-api-key")
# Ou via une variable d'environnement (recommandé pour la production)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Galvenās atziņas
- Le point de terminaison
/audio/transcriptionsest synchrone : envoyez le fichier, recevez le texte. - Deux modes de téléversement : téléversement direct (
file) ou URL publique (file_url). - Paramètres optionnels :
language,timestamp_granularities,diarize,context_bias. - Dans Voxtral 2,
languageettimestamp_granularitiesétaient mutuellement exclusifs ; la documentation de Voxtral 3 ne l’indique plus. - Les formats audio courants sont pris en charge ; la limite est la fenêtre de contexte partagée entre l’audio et
context_bias(erreur 400 si dépassée). - La diarisation et les horodatages peuvent être combinés.