Transcription de fichiers

La transcription de fichiers transforme un enregistrement dont vous disposez déjà — un appel, une réunion ou un épisode de podcast — en texte grâce à une seule requête. Cette page explique comment envoyer l'audio, quels champs de la requête modifient le résultat et comment obtenir des horodatages ou une réponse en streaming.

Référence API — POST /v1/audio/transcriptions

Information

La transcription de fichiers est le mode hors ligne : l'enregistrement complet existe avant son envoi. Pour un audio encore en cours d'enregistrement, comme un microphone ou une ligne téléphonique, utilisez Transcription en temps réel. Audio hors ligne et en temps réel explique la différence entre les deux modes.

Choisir votre source audio

L'audio parvient à l'API de trois manières, et chaque requête en utilise exactement une :

Entrée	Champ	Quand l'utiliser
Fichier audio	`file`	L'enregistrement se trouve sur votre machine ou votre serveur.
URL audio	`file_url`	L'enregistrement est déjà hébergé à une URL accessible par l'API.
Fichier importé	`file_id`	Vous avez importé l’enregistrement dans l’API Files avec `purpose=audio`, par exemple pour le transcrire plusieurs fois.

Chaque onglet n'affiche que la partie de la requête qui change. Le reste de la requête est le même que dans Envoyer une requête et lire le résultat.

  -F file=@obama.mp3

  -F file=@obama.mp3

Astuce

Quand vous n’avez plus besoin d’un enregistrement importé, supprimez-le avec DELETE /v1/files/{file_id}.

Pour connaître les formats audio acceptés et la taille maximale des fichiers, voir Formats audio et Limites.

Envoyer une requête et lire le résultat

Cette requête envoie un enregistrement local d'un appel d'assistance et renvoie sa transcription :

import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

with open("customer_call.wav", "rb") as audio:
    transcription = client.audio.transcriptions.complete(
        model="voxtral-mini-transcribe-3",
        file={"file_name": "customer_call.wav", "content": audio},
    )

print(transcription.model_dump_json(indent=2))

import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

with open("customer_call.wav", "rb") as audio:
    transcription = client.audio.transcriptions.complete(
        model="voxtral-mini-transcribe-3",
        file={"file_name": "customer_call.wav", "content": audio},
    )

print(transcription.model_dump_json(indent=2))

La réponse contient la transcription complète dans text :

{
  "model": "voxtral-mini-transcribe-3",
  "text": "Thanks for calling Northwind Support. This is Daniel. How can I help you today? Hi Daniel. I ordered two Quilliera headsets last week. Order 4417. And the tracking page still says pending. [...] Of course. I will email the tracking link today and ask billing to issue the invoice by Friday. Perfect. Thank you.",
  "language": null,
  "segments": [],
  "usage": {
    "prompt_audio_seconds": 34,
    "prompt_tokens": 3,
    "total_tokens": 879,
    "completion_tokens": 126,
    "prompt_tokens_details": {
      "cached_tokens": 1,
      "audio_tokens": 750
    },
    "service_tier": "standard"
  },
  "finish_reason": null
}

{
  "model": "voxtral-mini-transcribe-3",
  "text": "Thanks for calling Northwind Support. This is Daniel. How can I help you today? Hi Daniel. I ordered two Quilliera headsets last week. Order 4417. And the tracking page still says pending. [...] Of course. I will email the tracking link today and ask billing to issue the invoice by Friday. Perfect. Thank you.",
  "language": null,
  "segments": [],
  "usage": {
    "prompt_audio_seconds": 34,
    "prompt_tokens": 3,
    "total_tokens": 879,
    "completion_tokens": 126,
    "prompt_tokens_details": {
      "cached_tokens": 1,
      "audio_tokens": 750
    },
    "service_tier": "standard"
  },
  "finish_reason": null
}

Les autres champs :

segments reste vide, sauf si vous demandez des horodatages. Dans ce cas, c'est une liste de segments de transcription, chacun avec son heure de début et de fin, et avec l'étiquette du locuteur dans speaker_id si vous définissez aussi diarize.
language vaut null, même lorsque vous fixez la langue. Pour obtenir la langue détectée dans la réponse lorsque vous ne la fixez pas, définissez return_language sur true.
usage.prompt_audio_seconds correspond à la durée de l'audio traité par le modèle, exprimée en secondes.

Champs utiles pour la requête

Ces champs modifient le résultat renvoyé. Envoyez-les sous forme de champs de formulaire multipart. Pour la liste complète des champs, voir la Référence API.

Champ	Rôle	Détails
`model`	Obligatoire. `voxtral-mini-transcribe-3` ou `voxtral-small-transcribe-3`.	Choisir votre modèle
`file`, `file_url` ou `file_id`	L'audio à transcrire. Envoyez exactement un seul de ces champs.	Choisir votre source audio
`language`	La langue de l'audio, sous forme de code à deux lettres comme `fr`. Omettez-le pour laisser le modèle la détecter.	Fixer la langue
`timestamp_granularities`	Définissez-le sur `segment` pour obtenir chaque segment de la transcription avec ses temps de début et de fin. Omettez-le pour n'obtenir que le texte. Les horodatages au niveau du mot ne sont pas disponibles.	Horodatages
`diarize`	Définissez-le sur `true` pour étiqueter chaque segment avec son locuteur. Nécessite `timestamp_granularities=segment`.	Identifier les locuteurs
`context_bias`	Des noms et des termes que le modèle doit orthographier correctement, ou du texte libre qui donne du contexte sur l'enregistrement. Répétez le champ une fois par entrée. Vocabulaire personnalisé explique quand il est utile.	Biais contextuels
`stream`	Définissez-le sur `true` pour recevoir la transcription par fragments sous forme d'événements envoyés par le serveur.	Diffuser la réponse en streaming

Fixer la langue

Par défaut, le modèle détecte la langue de l'enregistrement. Si vous la connaissez à l'avance, transmettez-la dans language sous forme de code ISO 639-1 à deux lettres :

curl https://api.mistral.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -F model=voxtral-mini-transcribe-3 \
  -F file=@meeting_fr.wav \
  -F language=fr

curl https://api.mistral.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -F model=voxtral-mini-transcribe-3 \
  -F file=@meeting_fr.wav \
  -F language=fr

Fixer la langue peut améliorer la précision. Omettez-la quand vous ne connaissez pas la langue à l'avance. Pour les langues prises en charge et leurs codes, voir Langues.

Horodatages

Les horodatages des segments indiquent le moment où chaque partie de la transcription a été prononcée. Vous en avez besoin pour les sous-titres, pour les étiquettes de locuteurs et pour accéder directement à un moment de l'enregistrement. Ajoutez timestamp_granularities=segment à la requête :

curl https://api.mistral.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -F model=voxtral-mini-transcribe-3 \
  -F file=@customer_call.wav \
  -F timestamp_granularities=segment

curl https://api.mistral.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -F model=voxtral-mini-transcribe-3 \
  -F file=@customer_call.wav \
  -F timestamp_granularities=segment

La réponse conserve le text complet et remplit segments. Les trois premiers segments sont les suivants :

{
  "segments": [
    {
      "type": "transcription_segment",
      "text": "Thanks for calling Northwind Support.",
      "start": 0.0,
      "end": 1.6,
      "speaker_id": null
    },
    {
      "type": "transcription_segment",
      "text": " This is Daniel.",
      "start": 1.7,
      "end": 2.4,
      "speaker_id": null
    },
    {
      "type": "transcription_segment",
      "text": " How can I help you today?",
      "start": 2.6,
      "end": 3.5,
      "speaker_id": null
    }
  ]
}

{
  "segments": [
    {
      "type": "transcription_segment",
      "text": "Thanks for calling Northwind Support.",
      "start": 0.0,
      "end": 1.6,
      "speaker_id": null
    },
    {
      "type": "transcription_segment",
      "text": " This is Daniel.",
      "start": 1.7,
      "end": 2.4,
      "speaker_id": null
    },
    {
      "type": "transcription_segment",
      "text": " How can I help you today?",
      "start": 2.6,
      "end": 3.5,
      "speaker_id": null
    }
  ]
}

Chaque segment contient :

text : les mots du segment. Il conserve son espace initial, ce qui permet de réassembler les segments pour retrouver la transcription complète.
start et end : la position du segment dans l'enregistrement, en secondes.
speaker_id : null, sauf si vous définissez aussi diarize, voir Identifier les locuteurs.

Note

Les horodatages ne sont disponibles que par segment. Une requête d'horodatages au niveau du mot renvoie une erreur.

Étiqueter les locuteurs

Pour savoir qui a prononcé chaque segment, ajoutez diarize=true à une requête avec des horodatages par segment. Chaque segment porte alors l'étiquette d'un locuteur, comme speaker_1, dans speaker_id :

curl https://api.mistral.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -F model=voxtral-mini-transcribe-3 \
  -F file=@customer_call.wav \
  -F timestamp_granularities=segment \
  -F diarize=true

curl https://api.mistral.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -F model=voxtral-mini-transcribe-3 \
  -F file=@customer_call.wav \
  -F timestamp_granularities=segment \
  -F diarize=true

Pour nommer les locuteurs, lire les segments qui se chevauchent ou identifier les locuteurs en temps réel, voir Identifier les locuteurs.

Orthographier correctement les noms et les termes

Quand l'enregistrement contient des noms, des termes de produit ou du jargon, listez-les dans context_bias, une entrée par terme. Le modèle privilégie ces orthographes pendant la transcription :

curl https://api.mistral.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -F model=voxtral-mini-transcribe-3 \
  -F file=@customer_call.wav \
  -F context_bias=Northwind \
  -F context_bias=Quillara \
  -F "context_bias=Alder Creek Design"

curl https://api.mistral.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -F model=voxtral-mini-transcribe-3 \
  -F file=@customer_call.wav \
  -F context_bias=Northwind \
  -F context_bias=Quillara \
  -F "context_bias=Alder Creek Design"

Pour utiliser du texte libre comme contexte, connaître les limites ou utiliser les biais en temps réel, voir Biais contextuels.

Diffuser la réponse en streaming

Avec stream=true, l'API envoie la transcription par fragments au fur et à mesure de son écriture, ce qui permet à votre application d'afficher les premiers mots d'un enregistrement long sans attendre le résultat complet :

import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

with open("customer_call.wav", "rb") as audio:
    with client.audio.transcriptions.stream(
        model="voxtral-mini-transcribe-3",
        file={"file_name": "customer_call.wav", "content": audio},
    ) as events:
        for event in events:
            if event.event == "transcription.text.delta":
                print(event.data.text, end="", flush=True)
            elif event.event == "transcription.done":
                print(f"\n\nDone: {event.data.usage.prompt_audio_seconds} s of audio")

import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

with open("customer_call.wav", "rb") as audio:
    with client.audio.transcriptions.stream(
        model="voxtral-mini-transcribe-3",
        file={"file_name": "customer_call.wav", "content": audio},
    ) as events:
        for event in events:
            if event.event == "transcription.text.delta":
                print(event.data.text, end="", flush=True)
            elif event.event == "transcription.done":
                print(f"\n\nDone: {event.data.usage.prompt_audio_seconds} s of audio")

Le flux est une série d'événements envoyés par le serveur :

event: transcription.text.delta
data: {"type":"transcription.text.delta","text":"Thanks"}

event: transcription.text.delta
data: {"type":"transcription.text.delta","text":" for"}

...

event: transcription.done
data: {"model":"voxtral-mini-transcribe-3","text":"Thanks for calling Northwind Support. [...]","language":null,"segments":[],"usage":{"prompt_audio_seconds":34,...},"finish_reason":null,"type":"transcription.done"}

event: transcription.text.delta
data: {"type":"transcription.text.delta","text":"Thanks"}

event: transcription.text.delta
data: {"type":"transcription.text.delta","text":" for"}

...

event: transcription.done
data: {"model":"voxtral-mini-transcribe-3","text":"Thanks for calling Northwind Support. [...]","language":null,"segments":[],"usage":{"prompt_audio_seconds":34,...},"finish_reason":null,"type":"transcription.done"}

Pour le consommer :

Ajoutez le text de chaque événement transcription.text.delta à ce que vous affichez.
Quand vous recevez transcription.done, utilisez sa charge utile comme résultat final : elle contient les mêmes champs qu'une réponse sans streaming, y compris usage.

La référence API liste les autres types d'événements qu'un flux peut transporter : transcription.language, transcription.segment.delta (avec speaker_id, start et end) et transcription.done.

Information

Le streaming n'accélère pas la transcription elle-même, et ce n'est pas de la transcription en temps réel : l'enregistrement complet est d'abord envoyé, et seul le résultat arrive par fragments. Voir Latence.

Problèmes courants

Ces erreurs proviennent d'un champ de la requête. Corrigez le champ, puis envoyez à nouveau la requête :

Erreur	Cause	Solution
400 `Word-level segments are not enabled for this model`	`timestamp_granularities=word`	Utilisez `segment`.
422 quand vous définissez `diarize`	Diarisation sans horodatages de segments	Ajoutez `timestamp_granularities=segment`.
422 `Invalid language alpha2 code`	`language` n'est pas un code à deux lettres	Utilisez un code de Langues, comme `en` ou `fr`.
400 `maximum context length`	Pris ensemble, l'audio et les entrées `context_bias` dépassent le contexte du modèle. Rien n'est tronqué : la requête échoue.	Raccourcissez la liste `context_bias`, voir Biais contextuels.

Astuce

Pour les problèmes liés à la transcription elle-même, comme un audio bruité, des locuteurs qui parlent en même temps ou des noms mal orthographiés, voir Résolution des problèmes de reconnaissance vocale.

Aller plus loin

Identifier les locuteurs

Biais contextuels

Résolution des problèmes