L'API Voices

L’endpoint /v1/voices

L’API Voices de Mistral est le point d’entrée pour gérer vos voix personnalisées. Elle expose un ensemble d’opérations CRUD — Create, Read, Update, Delete — qui vous permettent de créer, lister, consulter, modifier et supprimer des voix. Si vous avez déjà manipulé une API REST classique, vous êtes en terrain connu : rien ici ne relève de l’audio proprement dit, il s’agit de gérer un catalogue d’objets.

Chaque voix créée via l’API reçoit un identifiant unique, le voice_id, que vous utiliserez ensuite pour générer de la parole. Retenez surtout ceci : les voix sont persistantes. Une fois créées, elles restent disponibles dans votre compte jusqu’à suppression explicite. Vous n’avez donc pas à ré-envoyer l’échantillon audio à chaque génération, et vos applications peuvent se contenter de stocker une chaîne de caractères en configuration.

Créer une voix

La création se fait via un appel POST à l’endpoint /v1/voices. Vous fournissez un échantillon audio encodé en base64 et des métadonnées descriptives :

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="votre-cle-api")

# Encoder l'échantillon audio en base64
sample_audio_b64 = base64.b64encode(
    Path("echantillon.mp3").read_bytes()
).decode()

# Créer la voix
voice = client.audio.voices.create(
    name="ma-voix-pro",
    sample_audio=sample_audio_b64,
    sample_filename="echantillon.mp3",
    languages=["fr", "en"],
    gender="female",
    age=35,
    tags=["professionnel", "podcast"]
)

print(f"Voix créée : {voice.id}")

Le passage par base64 s’explique simplement : la requête est un document JSON, et JSON ne transporte pas de binaire. L’API retourne un objet contenant le voice_id que vous conserverez pour toutes les requêtes de génération — dans l’exemple ci-dessus, on l’affiche, mais en production vous l’écrirez dans votre configuration ou votre base de données.

Lister, consulter, modifier

Pour récupérer la liste de toutes vos voix, la méthode list() accepte une pagination :

# Récupérer les 10 premières voix
voices = client.audio.voices.list(limit=10, offset=0)

for v in voices.data:
    print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")

La pagination est de type offset-based : vous spécifiez le nombre d’éléments avec limit et le décalage avec offset. Pour obtenir la deuxième page de dix voix, vous appelez donc la méthode avec offset=10. Cette mécanique devient utile dès qu’une agence gère les voix de plusieurs dizaines de clients.

Lorsque vous ne voulez qu’une voix précise, retrieve() renvoie ses métadonnées détaillées :

voice = client.audio.voices.retrieve(voice_id="votre-voice-id")

print(f"Nom : {voice.name}")
print(f"Genre : {voice.gender}")
print(f"Langues : {voice.languages}")
print(f"Tags : {voice.tags}")

Le réflexe à prendre est d’appeler cette opération avant une génération importante, pour vérifier que le voice_id codé dans votre application pointe bien sur la voix attendue et non sur celle d’un ancien projet.

Les métadonnées d’une voix existante se modifient ensuite sans toucher à l’échantillon audio :

updated_voice = client.audio.voices.update(
    voice_id="votre-voice-id",
    name="ma-voix-pro-v2",
    languages=["fr", "en", "es"],
    tags=["professionnel", "podcast", "multilingual"]
)

print(f"Voix mise à jour : {updated_voice.name}")

Les champs modifiables sont name, languages, gender, age et tags. L’échantillon audio original, lui, ne peut pas être modifié : si vous souhaitez changer l’audio, vous devez créer une nouvelle voix. Concrètement, une voix mal enregistrée ne se répare pas — elle se remplace, et vous devrez propager le nouveau voice_id dans vos applications.

Supprimer, et récupérer l’échantillon

La suppression est permanente et irréversible :

client.audio.voices.delete(voice_id="votre-voice-id")
print("Voix supprimée")

Après suppression, toute requête de génération utilisant ce voice_id échouera. Le scénario à redouter est classique : un développeur fait le ménage dans les voix de test, en efface une qui alimentait en réalité le serveur vocal du support, et l’incident se déclare le lendemain matin au premier appel entrant. Assurez-vous donc de mettre à jour vos applications avant de supprimer une voix en production.

Vous pouvez par ailleurs télécharger l’audio original utilisé pour créer une voix :

audio_bytes = client.audio.voices.sample(voice_id="votre-voice-id")
Path("echantillon_recupere.mp3").write_bytes(audio_bytes)

Cette fonctionnalité sert à archiver vos échantillons ou à vérifier la qualité de l’audio source lorsqu’une voix vous déçoit : en réécoutant l’original, on découvre souvent que le défaut entendu à la génération était déjà présent à l’enregistrement.

Organiser son catalogue de voix

Une gestion propre coûte peu et évite beaucoup de confusion. Nommez clairement vos voix avec un préfixe de projet, sur le modèle podcast-narrateur ou app-assistant-fr, plutôt que voix1 et test-final-2. Utilisez les tags pour catégoriser par usage, projet ou client, ce qui rend les listes exploitables quand elles s’allongent. Documentez les voice_id dans votre configuration applicative, jamais dans un fichier isolé sur un poste de travail. Et ne supprimez jamais une voix en production sans avoir vérifié au préalable qu’elle n’est plus référencée nulle part.

Points clés à retenir

• L’API Voices expose un CRUD complet : créer, lister, récupérer, modifier, supprimer
• Chaque voix reçoit un voice_id unique utilisé dans les requêtes de génération
• La pagination offset-based permet de gérer un grand nombre de voix
• La suppression est permanente — toutes les requêtes utilisant ce voice_id échoueront
• L’échantillon audio original peut être récupéré via l’endpoint sample