L'API de Transcription Offline

L’endpoint de transcription

L’API de transcription offline de Mistral utilise l’endpoint /audio/transcriptions. C’est une API synchrone : vous envoyez un fichier audio, la requête reste ouverte pendant le traitement, et vous récupérez la transcription complète dans la réponse. Aucune notion de tâche à interroger, aucun webhook à câbler — ce qui simplifie beaucoup le code, mais implique de prévoir des délais d’attente généreux sur les fichiers longs.

Trois prérequis avant de coder : un compte sur la plateforme Mistral (console.mistral.ai), une clé API active, et le SDK Python installé.

Installation du SDK

pip install mistralai

Les paramètres de l’appel

Tout passe par client.audio.transcriptions.complete(). Deux paramètres sont obligatoires, quatre sont optionnels — et ce sont ces derniers qui font la différence entre une transcription brute et un livrable exploitable.

Paramètres obligatoires

• model — L’identifiant du modèle. Pour la transcription offline : "voxtral-mini-latest" (recommandé) ou "voxtral-mini-2602" (version figée).
• file ou file_url — Le fichier audio à transcrire. Deux options :
  • file : un dictionnaire {"content": file_object, "file_name": "nom.mp3"} pour un upload direct
  • file_url : une URL publique pointant vers le fichier audio

Le choix entre file et file_url est d’abord une question d’architecture. Si votre audio est déjà stocké sur un espace accessible publiquement, file_url évite de le faire transiter par votre serveur. S’il vient d’un poste utilisateur ou d’un stockage privé, l’upload direct s’impose.

Paramètres optionnels

Quatre réglages facultatifs changent la nature de ce que vous récupérez. language attend un code ISO de langue — "fr", "en" — et court-circuite la détection automatique. Vous le forcerez sur un lot homogène, par exemple un catalogue d’entretiens tous menés en français, pour éviter qu’un passage anglophone fasse basculer le modèle en cours de fichier. Retenez d’emblée qu’il est incompatible avec timestamp_granularities.

timestamp_granularities prend justement une liste de granularités — ["segment"], ["word"] ou ["segment", "word"] — et déclenche le retour des horodatages. C’est ce paramètre qui rend possible un fichier de sous-titres calé sur l’image, ou un index par passage dans une conférence de deux heures.

diarize est un booléen : à True, le modèle identifie les locuteurs et rattache chaque segment à l’un d’eux. Sur un comité de direction à six voix, c’est la différence entre un mur de texte anonyme et un compte-rendu où chaque engagement est attribuable.

context_bias, enfin, reçoit une chaîne de mots ou de phrases séparés par des virgules — jusqu’à 100 termes — pour améliorer la reconnaissance d’un vocabulaire spécifique. Une réunion d’ingénierie où reviennent « Kubernetes » et « RGPD » en sort nettement plus lisible.

Formats audio supportés

Voxtral accepte les formats courants, et vous n’aurez presque jamais à convertir quoi que ce soit en amont.

La durée maximale est de 3 heures par requête. Pour les fichiers plus longs — un séminaire d’une journée, par exemple — découpez-les avant l’envoi, de préférence sur des silences pour ne pas couper une phrase 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 timestamps (timestamp_granularities), la réponse inclut aussi :

response.segments      # Liste de segments avec start, end, text
response.words         # Liste de mots avec start, end, text (si word demandé)

Et si vous avez activé la diarisation (diarize=True), chaque segment s’enrichit de l’identité du locuteur :

segment.speaker        # Identifiant du locuteur (str)
segment.start          # Début en secondes (float)
segment.end            # Fin en secondes (float)
segment.text           # Texte du segment (str)

Autrement dit, la forme de l’objet retourné dépend de ce que vous avez demandé. Un code qui itère sur response.segments sans avoir passé timestamp_granularities échouera : vérifiez toujours la cohérence entre vos paramètres d’entrée et votre traitement de 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-latest",
    file={"content": f, "file_name": "audio.mp3"}
)

# Avec langue forcée (pas de timestamps)
client.audio.transcriptions.complete(
    model="voxtral-mini-latest",
    file={"content": f, "file_name": "audio.mp3"},
    language="fr"
)

# Avec timestamps par segment
client.audio.transcriptions.complete(
    model="voxtral-mini-latest",
    file={"content": f, "file_name": "audio.mp3"},
    timestamp_granularities=["segment"]
)

# Avec diarisation + timestamps
client.audio.transcriptions.complete(
    model="voxtral-mini-latest",
    file={"content": f, "file_name": "audio.mp3"},
    diarize=True,
    timestamp_granularities=["segment"]
)

# Avec context biasing
client.audio.transcriptions.complete(
    model="voxtral-mini-2602",
    file_url="https://example.com/audio.mp3",
    context_bias="Mistral,Voxtral,Corsen,RGPD"
)

Une contrainte mérite d’être mémorisée dès maintenant, car elle surprend systématiquement : language et timestamp_granularities ne peuvent pas être utilisés ensemble dans le même appel. Si votre projet exige les deux, vous ferez deux appels séparés ou vous laisserez la détection automatique faire son travail.

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, la variable d’environnement évite que la clé finisse dans votre dépôt Git.

from mistralai import Mistral

# Via argument direct
client = Mistral(api_key="votre-cle-api")

# Ou via variable d'environnement (recommandé en production)
import os
os.environ["MISTRAL_API_KEY"] = "votre-cle-api"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Points clés à retenir

• L’endpoint /audio/transcriptions est synchrone : envoi du fichier, réception du texte
• Deux modes d’envoi : upload direct (file) ou URL publique (file_url)
• Paramètres optionnels : language, timestamp_granularities, diarize, context_bias
• language et timestamp_granularities sont mutuellement exclusifs
• Formats supportés : MP3, WAV, FLAC, OGG, M4A, WEBM — jusqu’à 3 heures
• La diarisation et les timestamps peuvent être combinés