Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

L'API de transcription hors ligne

Paskaita 4 iš 16 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Le point de terminaison de transcription
  2. Paramètres d’appel
  3. Formats audio pris en charge
  4. Structure de la réponse
  5. Combinaisons de paramètres
  6. Authentification
  7. Svarbiausi punktai

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 par voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 et voxtral-mini-tts-3-0. Changements clés : les horodatages sont uniquement par segment (word renvoie 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 chunk audio, et les entrées context_bias sont 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. C’est une API synchrone : tu envoies un fichier audio, la requête reste ouverte pendant le traitement, et tu reçois 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 ton code, mais tu dois prévoir des délais d’attente généreux pour les fichiers longs.

Avant de commencer à coder, assure-toi 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, utilise "voxtral-mini-transcribe-3" (recommandé) ou une version épinglée comme "voxtral-mini-transcribe-3".
  • file ou file_url — Le fichier audio à transcrire. Tu as 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.

Choisir entre file et file_url est une décision d’architecture. Si ton audio est déjà stocké à un emplacement accessible publiquement, file_url évite de faire transiter le fichier par ton 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. Force 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. Note 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é exécutif 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, donc garde 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 tu auras rarement besoin de convertir quoi que ce soit au préalable. En cas de doute, consulte la page Audio formats dans la documentation.

FormatCaractéristique
MP3Le plus courant, bonne compression
WAVNon compressé, qualité maximale
FLACCompression sans perte
OGGFormat ouvert, bonne compression
M4A / AACFormat Apple, courant sur mobile
WEBMFormat 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écoupe-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 tu as demandé des horodatages (timestamp_granularities), la réponse inclut également :

response.segments      # Liste de segments avec début, fin, texte

Si tu as 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 ta requête. Un code qui itère sur response.segments sans passer timestamp_granularities échouera. Vérifie toujours la cohérence entre tes paramètres d’entrée et ton traitement de sortie.

Combinaisons de paramètres

Voici les cinq combinaisons valides que tu rencontreras 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érifie cela par un test avant de t’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, utilise une variable d’environnement pour éviter que la clé ne se retrouve dans ton 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"])

Svarbiausi punktai

  • Le point de terminaison /audio/transcriptions est synchrone : envoie le fichier, reçois 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, language et timestamp_granularities s’excluaient mutuellement ; la documentation de Voxtral 3 n’indique plus cela.
  • 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.