De Voices API
Op deze pagina
Cursus bijgewerkt op 3 november 2026 voor Voxtral TTS 3, gebaseerd op de gids Migrate from Voxtral 2 en de pagina’s Text to Speech van Mistral:
voxtral-mini-tts-2603, verouderd op 31 oktober 2026 en verwijderd op 30 april 2027, wordt in voorbeelden vervangen doorvoxtral-mini-tts-3-0. Vooraf gedefinieerde stemmen van Voxtral 2 (gb_jane_neutral…) blijven geaccepteerd; Voxtral 3 voegt[emotion=…]- en[pace=…]-tags in tekst toe, deexpressiveness-instelling, aangepaste uitspraak (phoneme_hints) en ondersteuning voor 35 talen. Mistral raadt aan de latentie opnieuw te meten na migratie. Bronnen: Migrate from Voxtral 2 · Speech generation.
Het /v1/voices-eindpunt
De Voices API van Mistral is uw toegangspoort voor het beheren van aangepaste stemmen. Het biedt een volledige set CRUD-bewerkingen (Create, Read, Update, Delete), waarmee u stemmen kunt maken, opsommen, ophalen, wijzigen en verwijderen. Als u eerder met een standaard REST API hebt gewerkt, bent u op vertrouwd terrein: hier wordt niets direct gerelateerd aan audiobewerking; dit gaat puur over het beheren van een catalogus van objecten.
Elke via de API gemaakte stem ontvangt een unieke identifier, de voice_id, die u later gebruikt om spraak te genereren. Houd dit in gedachten: stemmen zijn persistent. Eenmaal gemaakt, blijven ze beschikbaar in uw account totdat ze expliciet worden verwijderd. U hoeft het audiofragment niet voor elke generatie opnieuw te verzenden, zodat uw applicaties slechts een string in hun configuratie hoeven op te slaan.
Een stem maken
Het maken gebeurt via een POST-aanroep naar het /v1/voices-eindpunt. U levert een audiofragment gecodeerd in base64 samen met beschrijvende metadata:
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Encodeer het audiofragment naar base64
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Maak de stem aan
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}")
Het gebruik van base64 is noodzakelijk omdat het verzoek een JSON-document is en JSON geen binaire gegevens kan bevatten. De API retourneert een object dat de voice_id bevat, die u voor alle generatieverzoeken bewaart. In het bovenstaande voorbeeld printen we deze, maar in een productieomgeving moet u deze naar uw configuratie of database schrijven.
Opsommen, ophalen en wijzigen
Om een lijst van al uw stemmen op te halen, ondersteunt de list()-methode paginatie:
# Haal de eerste 10 stemmen op
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
Paginatie is offset-gebaseerd: u geeft het aantal items op met limit en het startpunt met offset. Om ook de vooraf gedefinieerde stemmen van Mistral te doorzoeken (Marie in het Frans, fr_marie_neutral, Jane in Brits-Engels, enz.), somt voices.search beide families op, onderscheiden door het veld type: preset of custom. Om de tweede pagina van tien stemmen op te halen, roept u de methode aan met offset=10. Dit mechanisme wordt nuttig zodra een bureau stemmen voor tientallen klanten beheert.
Wanneer u details over een specifieke stem nodig hebt, retourneert get() de volledige metadata:
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}")
Maak er een gewoonte van om deze bewerking aan te roepen voordat u een grote generatietaak uitvoert. Hiermee verifieert u dat de voice_id die in uw applicatie is vastgelegd, verwijst naar de verwachte stem en niet naar een stem uit een oud project.
U kunt de metadata van een bestaande stem wijzigen zonder het audiofragment aan te raken:
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}")
Wijzigbare velden zijn name, languages, gender, age, tags en description. Het oorspronkelijke audiofragment kan echter niet worden gewijzigd. Als u de audio wilt wijzigen, moet u een nieuwe stem maken. In de praktijk kan een slecht opgenomen stem niet worden gerepareerd; deze moet worden vervangen, en u zult de nieuwe voice_id in al uw applicaties moeten doorvoeren.
Verwijderen en het fragment ophalen
Verwijderen is definitief en onomkeerbaar:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Na verwijdering zal elk generatieverzoek dat deze voice_id gebruikt, mislukken. Een klassiek nachtmerriescenario: een ontwikkelaar ruimt teststemmen op, verwijdert per ongeluk een stem die daadwerkelijk de support-IVR aandrijft, en het incident breekt de volgende ochtend uit bij de eerste binnenkomende oproep. Zorg er altijd voor dat uw applicaties zijn bijgewerkt voordat u een stem in productie verwijdert.
U kunt ook de originele audio downloaden die is gebruikt om een stem te maken:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Deze functie helpt u uw fragmenten te archiveren of de kwaliteit van de bronaudio te verifiëren als een stem u teleurstelt. Door naar het origineel te luisteren, ontdekt u vaak dat het gebrek dat tijdens de generatie werd gehoord, al in de opname aanwezig was.
Uw stammencatalogus organiseren
Schoon beheer kost weinig en voorkomt aanzienlijke verwarring. Geef uw stemmen duidelijke namen met een projectprefix, volgens patronen zoals podcast-narrator of app-assistant-fr, in plaats van voice1 en test-final-2. Gebruik tags om te categoriseren op gebruiksscenario, project of klant, zodat lijsten beheersbaar blijven naarmate ze groeien. Documenteer voice_ids in uw applicatieconfiguratie, nooit in een geïsoleerd bestand op een werkstation. En verwijder nooit een productiestem zonder eerst te verifiëren dat deze nergens meer wordt gebruikt.
Belangrijkste punten
- De Voices API biedt volledige CRUD-mogelijkheden: maken, opsommen, ophalen, bijwerken, verwijderen
- Elke stem ontvangt een unieke
voice_iddie wordt gebruikt in generatieverzoeken - Offset-gebaseerde paginatie stelt u in staat een groot aantal stemmen te beheren
- Verwijdering is definitief; alle verzoeken die deze voice_id gebruiken, zullen mislukken
- Het oorspronkelijke audiofragment kan worden opgehaald via het sample-eindpunt