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 et recevez la transcription complète dans la réponse.

Avant de coder, assurez-vous d’avoir :

1. Un compte sur la plateforme Mistral (console.mistral.ai)
2. Une clé API active
3. Le SDK Python Mistral installé

Installation du SDK

pip install mistralai

L’endpoint et ses paramètres

L’appel principal utilise client.audio.transcriptions.complete() avec les paramètres suivants :

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

Paramètres optionnels

• language — Code ISO de la langue (ex: "fr", "en"). Si omis, la langue est détectée automatiquement. Incompatible avec timestamp_granularities.
• timestamp_granularities — Liste de granularités : ["segment"], ["word"], ou ["segment", "word"]. Active le retour de timestamps.
• diarize — Booléen. Si True, identifie les locuteurs dans la transcription.
• context_bias — Chaîne de caractères contenant des mots/phrases séparés par des virgules. Jusqu’à 100 termes pour améliorer la reconnaissance de vocabulaire spécifique.

Formats audio supportés

Voxtral accepte les formats audio courants :

• 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 durée maximale est de 3 heures par requête. Pour les fichiers plus longs, découpez-les avant l’envoi.

Structure de la réponse

La réponse contient au minimum :

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é)

Si vous avez activé la diarisation (diarize=True), chaque segment inclut :

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)

Combinaisons de paramètres

Certains paramètres sont mutuellement exclusifs. Voici les combinaisons valides :

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

Attention : language et timestamp_granularities ne peuvent pas être utilisés ensemble dans le même appel.

Authentification

Toutes les requêtes nécessitent une clé API valide, passée au constructeur du client :

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