L'API Voices
In questa pagina
Cours mis à jour le 3 novembre 2026 pour Voxtral TTS 3, sur la base du guide Migrate from Voxtral 2 et des pages Text to Speech de Mistral :
voxtral-mini-tts-2603, déprécié le 31 octobre 2026 et supprimé le 30 avril 2027, est remplacé dans les exemples parvoxtral-mini-tts-3-0. Les voix prédéfinies de Voxtral 2 (gb_jane_neutral…) restent acceptées ; Voxtral 3 ajoute les balises[emotion=…]et[pace=…]dans le texte, le paramètreexpressiveness, la prononciation personnalisée (phoneme_hints) et prend en charge 35 langues. Mistral recommande de remesurer la latence après la migration. Sources : Migrate from Voxtral 2 · Speech generation.
Le point de terminaison /v1/voices
L’API Voices de Mistral est ton point d’entrée pour gérer les voix personnalisées. Elle expose un ensemble complet d’opérations CRUD (Create, Read, Update, Delete), te permettant de créer, lister, récupérer, modifier et supprimer des voix. Si tu as déjà travaillé avec une API REST standard, tu es en terrain connu : rien ici ne traite directement du traitement audio ; il s’agit purement de gérer un catalogue d’objets.
Chaque voix créée via l’API reçoit un identifiant unique, le voice_id, que tu utiliseras ultérieurement pour générer de la parole. Garde ceci en tête : les voix sont persistantes. Une fois créées, elles restent disponibles dans ton compte jusqu’à suppression explicite. Tu n’as pas besoin de renvoyer l’échantillon audio pour chaque génération, ainsi tes applications n’ont besoin de stocker qu’une chaîne de caractères dans leur configuration.
Création d’une voix
La création s’effectue via un appel POST au point de terminaison /v1/voices. Tu fournis un échantillon audio encodé en base64 accompagné de métadonnées descriptives :
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Encoder l'échantillon audio en base64
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Créer la voix
voice = client.audio.voices.create(
name="my-pro-voice",
sample_audio=sample_audio_b64,
sample_filename="sample.mp3",
languages=["fr", "en"],
gender="female",
age=35,
tags=["professional", "podcast"]
)
print(f"Voice created: {voice.id}")
L’utilisation du base64 est nécessaire car la requête est un document JSON, et le JSON ne peut pas transporter de données binaires. L’API renvoie un objet contenant le voice_id que tu conserveras pour toutes les demandes de génération. Dans l’exemple ci-dessus, nous l’affichons, mais en production, tu devrais l’écrire dans ta configuration ou ta base de données.
Listage, récupération et modification
Pour récupérer la liste de toutes tes voix, la méthode list() prend en charge la pagination :
# Obtenir les 10 premières voix
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
La pagination est basée sur le décalage (offset) : tu spécifies le nombre d’éléments avec limit et le point de départ avec offset. Pour parcourir également les voix prédéfinies de Mistral (Marie en français, fr_marie_neutral, Jane en anglais britannique, etc.), voices.search liste les deux familles, distinguées par le champ type : preset ou custom. Pour obtenir la deuxième page de dix voix, tu appelles la méthode avec offset=10. Ce mécanisme devient utile dès qu’une agence gère des voix pour des dizaines de clients.
Lorsque tu as besoin de détails sur une voix spécifique, get() renvoie ses métadonnées complètes :
voice = client.audio.voices.get(voice_id="your-voice-id")
print(f"Name: {voice.name}")
print(f"Gender: {voice.gender}")
print(f"Languages: {voice.languages}")
print(f"Tags: {voice.tags}")
Prends l’habitude d’appeler cette opération avant une session de génération majeure. Cela vérifie que le voice_id codé en dur dans ton application pointe bien vers la voix attendue et non vers celle d’un ancien projet.
Tu peux modifier les métadonnées d’une voix existante sans toucher à l’échantillon audio :
updated_voice = client.audio.voices.update(
voice_id="your-voice-id",
name="my-pro-voice-v2",
languages=["fr", "en", "es"],
tags=["professional", "podcast", "multilingual"]
)
print(f"Voice updated: {updated_voice.name}")
Les champs modifiables incluent name, languages, gender, age, tags et description. L’échantillon audio original, en revanche, ne peut pas être modifié. Si tu souhaites changer l’audio, tu dois créer une nouvelle voix. En pratique, une voix mal enregistrée ne peut pas être réparée : elle doit être remplacée, et tu devras propager le nouveau voice_id dans toutes tes applications.
Suppression et récupération de l’échantillon
La suppression est définitive et irréversible :
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Après suppression, toute demande de génération utilisant ce voice_id échouera. Scénario cauchemardesque classique : un développeur nettoie les voix de test, en supprime accidentellement une qui alimente réellement le SVI du support client, et l’incident éclate le lendemain matin dès le premier appel entrant. Assure-toi toujours que tes applications sont mises à jour avant de supprimer une voix en production.
Tu peux également télécharger l’audio original utilisé pour créer une voix :
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Cette fonctionnalité t’aide à archiver tes échantillons ou à vérifier la qualité de l’audio source si une voix te déçoit. En écoutant l’original, tu découvres souvent que le défaut entendu lors de la génération était déjà présent dans l’enregistrement.
Organisation de ton catalogue de voix
Une gestion propre coûte peu et évite une confusion importante. Nomme tes voix clairement avec un préfixe de projet, en suivant des modèles comme podcast-narrator ou app-assistant-fr, plutôt que voice1 et test-final-2. Utilise des tags pour catégoriser par cas d’usage, projet ou client, rendant les listes gérables à mesure qu’elles grandissent. Documente les voice_id dans la configuration de ton application, jamais dans un fichier isolé sur un poste de travail. Et ne supprime jamais une voix de production sans avoir d’abord vérifié qu’elle n’est plus référencée nulle part.
Punti chiave
- L’API Voices expose des fonctionnalités CRUD complètes : créer, lister, récupérer, mettre à jour, supprimer
- Chaque voix reçoit un
voice_idunique utilisé dans les demandes de génération - La pagination basée sur le décalage te permet de gérer un grand nombre de voix
- La suppression est définitive : toutes les demandes utilisant ce voice_id échoueront
- L’échantillon audio original peut être récupéré via le point de terminaison des échantillons