Génération de Speech

Une requête Speech transforme un texte complet en fichier audio en un seul appel, avec la voix et le format de votre choix. Cette page présente la requête, les champs qui modifient le résultat et les erreurs que vous risquez le plus de rencontrer.

Envoyez le texte et une voix en une seule requête POST. La réponse contient l'audio, encodé en base64, dans audio_data : décodez-le et enregistrez-le dans un fichier.

import base64
import os
from pathlib import Path

from mistralai.client import Mistral

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

response = client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    input="Your order shipped this morning and should arrive on Thursday.",
    voice_id="gb_jane_neutral",
    response_format="mp3",
)

audio = base64.b64decode(response.audio_data)
output = Path("order_update.mp3")
output.write_bytes(audio)
print(f"Saved {output.resolve()} ({len(audio)} bytes)")

import base64
import os
from pathlib import Path

from mistralai.client import Mistral

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

response = client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    input="Your order shipped this morning and should arrive on Thursday.",
    voice_id="gb_jane_neutral",
    response_format="mp3",
)

audio = base64.b64decode(response.audio_data)
output = Path("order_update.mp3")
output.write_bytes(audio)
print(f"Saved {output.resolve()} ({len(audio)} bytes)")

Les exemples enregistrent le fichier order_update.mp3 dans le répertoire courant. Ouvrez-le dans n'importe quel lecteur audio pour l'écouter.

Le tableau suivant répertorie les champs qui modifient le plus souvent le résultat. Pour la liste complète, consultez la référence API.

Définissez response_format sur mp3 (valeur par défaut), wav, pcm, flac ou opus. Pour choisir entre eux, consultez Formats audio.

expressiveness définit à quel point l'audio généré suit ce que vous demandez : la voix, le texte et les éventuelles balises d'émotion ou instructions de style. Ce paramètre accepte des valeurs de 1.0 à 5.0.

Contrôle le caractère expressif de l'audio généré. Des valeurs plus élevées privilégient un rendu plus marqué, au détriment de la similitude de la voix et de la stabilité. Commencez avec la valeur par défaut, augmentez-la si l'émotion ne ressort pas, et diminuez-la si l'audio semble forcé.

Lorsque la parole fait partie d'une conversation, transmettez conversation_history pour donner au modèle le contexte dont il a besoin afin d'ajuster l'interprétation — ton, rythme et emphase — et la faire correspondre au fil de la conversation. Le voice_id définit la voix et l'accent de la parole générée ; l'historique de conversation aide le modèle à prononcer la réponse de manière cohérente avec ce qui précède.

Sans conversation_history, le modèle génère la réponse à l'aveugle, sans aucune connaissance de la conversation précédente. Cela convient pour des messages autonomes (annonces, prompts, lecture d'un article), mais on perd le contexte conversationnel qui rend l'interprétation naturelle dans un dialogue.

conversation_history est un tableau de tours, du plus ancien au plus récent. Chaque tour est soit un tour utilisateur avec audio, soit un tour assistant avec texte et audio. Le nouveau input est la réponse de l'assistant au dernier tour utilisateur de l'historique.

L'audio de chaque tour est encodé en base64. L'historique doit être non vide, alterner entre user et assistant, et se terminer par un tour user.

import base64
import os
from pathlib import Path

from mistralai.client import Mistral

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

user_audio_1 = base64.b64encode(Path("user_turn_1.wav").read_bytes()).decode()
assistant_audio = base64.b64encode(Path("assistant_turn.wav").read_bytes()).decode()
user_audio_2 = base64.b64encode(Path("user_turn_2.wav").read_bytes()).decode()

response = client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    voice_id="voice_592",
    input="I'm sorry about the delay. Let me check that for you.",
    response_format="wav",
    additional_properties={
        "conversation_history": [
            {"role": "user", "audio": {"data": user_audio_1}},
            {"role": "assistant", "text": "How can I help you today?", "audio": {"data": assistant_audio}},
            {"role": "user", "audio": {"data": user_audio_2}},
        ]
    },
)

audio = base64.b64decode(response.audio_data)
Path("reply.wav").write_bytes(audio)
print(f"Saved reply.wav ({len(audio)} bytes)")

import base64
import os
from pathlib import Path

from mistralai.client import Mistral

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

user_audio_1 = base64.b64encode(Path("user_turn_1.wav").read_bytes()).decode()
assistant_audio = base64.b64encode(Path("assistant_turn.wav").read_bytes()).decode()
user_audio_2 = base64.b64encode(Path("user_turn_2.wav").read_bytes()).decode()

response = client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    voice_id="voice_592",
    input="I'm sorry about the delay. Let me check that for you.",
    response_format="wav",
    additional_properties={
        "conversation_history": [
            {"role": "user", "audio": {"data": user_audio_1}},
            {"role": "assistant", "text": "How can I help you today?", "audio": {"data": assistant_audio}},
            {"role": "user", "audio": {"data": user_audio_2}},
        ]
    },
)

audio = base64.b64decode(response.audio_data)
Path("reply.wav").write_bytes(audio)
print(f"Saved reply.wav ({len(audio)} bytes)")

Chaque tour nécessite audio: { data: string } avec un fichier audio encodé en base64. Les tours assistant nécessitent également text. L'historique doit se terminer par un tour user, et le nouveau input est la réponse de l'assistant à ce dernier tour.

Il s'agit des problèmes que vous risquez le plus de rencontrer avec une requête Speech. Pour la liste complète, consultez Dépannage.