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.

Chaque voix créée via l’API reçoit un identifiant unique (voice_id) que vous utiliserez ensuite pour générer de la parole. Les voix sont persistantes — une fois créées, elles restent disponibles dans votre compte jusqu’à suppression explicite.

Créer une voix

La création d’une voix 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}")

L’API retourne un objet contenant le voice_id que vous conserverez pour toutes les requêtes de génération.

Lister les voix

Pour récupérer la liste de toutes vos voix, utilisez la méthode list() avec 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 (limit) et le décalage (offset). C’est utile si vous gérez un grand nombre de voix.

Récupérer une voix

Pour obtenir les métadonnées détaillées d’une voix spécifique :

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}")

Cette opération est utile pour vérifier les propriétés d’une voix avant de l’utiliser dans une génération.

Mettre à jour une voix

Vous pouvez modifier les métadonnées d’une voix existante sans recréer 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 ne peut pas être modifié — si vous souhaitez changer l’audio, vous devez créer une nouvelle voix.

Supprimer une voix

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. Assurez-vous de mettre à jour vos applications avant de supprimer une voix en production.

Récupérer l’échantillon audio

Vous pouvez 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é est utile pour archiver vos échantillons ou vérifier la qualité de l’audio source.

Bonnes pratiques de gestion

Pour organiser efficacement vos voix :

• Nommez clairement vos voix avec un préfixe de projet (ex: podcast-narrateur, app-assistant-fr)
• Utilisez les tags pour catégoriser par usage, projet ou client
• Documentez les voice_id dans votre configuration applicative
• Ne supprimez jamais une voix en production sans vérifier qu’elle n’est plus référencée

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