Die Voices API
Auf dieser Seite
Kurs aktualisiert am 3. November 2026 für Voxtral TTS 3, basierend auf dem Leitfaden Migrate from Voxtral 2 und den Seiten von Mistral zu Text to Speech:
voxtral-mini-tts-2603, am 31. Oktober 2026 abgelehnt und am 30. April 2027 entfernt, wird in Beispielen durchvoxtral-mini-tts-3-0ersetzt. Die vordefinierten Stimmen von Voxtral 2 (gb_jane_neutral…) bleiben akzeptiert; Voxtral 3 fügt Tags[emotion=…]und[pace=…]im Text, die Einstellungexpressiveness, Aussprachehinweise (phoneme_hints) und 35 Sprachen hinzu. Mistral empfiehlt, die Latenz nach der Migration erneut zu messen. Quellen: Migrate from Voxtral 2 · Speech generation.
Der /v1/voices-Endpunkt
Die Voices API von Mistral ist Ihr Einstiegspunkt für das Verwalten benutzerdefinierter Stimmen. Sie stellt eine vollständige Reihe von CRUD-Operationen bereit – Create, Read, Update, Delete – mit der Sie Stimmen erstellen, auflisten, abrufen, ändern und löschen können. Wenn Sie bereits mit einer Standard-REST-API gearbeitet haben, befinden Sie sich auf vertrautem Terrain: Hier wird keine Audioverarbeitung direkt durchgeführt; es geht rein um die Verwaltung eines Katalogs von Objekten.
Jede Stimme, die über die API erstellt wird, erhält eine eindeutige Kennung, die voice_id, die Sie später zur Generierung von Sprache verwenden werden. Halten Sie dies im Hinterkopf: Stimmen sind persistent. Sobald erstellt, bleiben sie in Ihrem Konto verfügbar, bis sie explizit gelöscht werden. Sie müssen das Audiosample für jede Generierung nicht erneut senden; Ihre Anwendungen müssen lediglich einen String in ihrer Konfiguration speichern.
Erstellen einer Stimme
Die Erstellung erfolgt über einen POST-Aufruf an den /v1/voices-Endpunkt. Sie stellen ein Audiosample bereit, das in base64 codiert ist, sowie beschreibende Metadaten:
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Das Audiosample in base64 codieren
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Die Stimme erstellen
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"Stimme erstellt: {voice.id}")
Die Verwendung von base64 ist notwendig, da die Anfrage ein JSON-Dokument ist und JSON keine Binärdaten tragen kann. Die API gibt ein Objekt zurück, das die voice_id enthält, die Sie für alle Generierungsanfragen verwenden werden. Im obigen Beispiel geben wir sie aus, aber in der Produktion sollten Sie sie in Ihre Konfiguration oder Datenbank schreiben.
Auflisten, Abrufen und Ändern
Um eine Liste aller Ihrer Stimmen zu erhalten, unterstützt die list()-Methode Paginierung:
# Die ersten 10 Stimmen abrufen
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
Die Paginierung basiert auf Offsets: Sie geben die Anzahl der Elemente mit limit und den Startpunkt mit offset an. Um sowohl die vordefinierten Stimmen von Mistral (Marie auf Französisch, fr_marie_neutral, Jane auf British English usw.) als auch Ihre eigenen aufzulisten, listet voices.search beide Familien, die durch das Feld type unterschieden werden: preset oder custom. Um die zweite Seite mit zehn Stimmen abzurufen, rufen Sie die Methode mit offset=10 auf. Dieser Mechanismus wird nützlich, sobald eine Agentur Stimmen für Dutzende von Kunden verwaltet.
Wenn Sie Details zu einer bestimmten Stimme benötigen, gibt get() die vollständigen Metadaten zurück:
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}")
Machen Sie es zur Gewohnheit, diese Operation vor einem großen Generierungslauf aufzurufen. Dies überprüft, dass die voice_id, die in Ihrer Anwendung hartcodiert ist, auf die erwartete Stimme und nicht auf eine aus einem alten Projekt zeigt.
Sie können die Metadaten einer bestehenden Stimme ändern, ohne das Audiosample anzufassen:
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"Stimme aktualisiert: {updated_voice.name}")
Änderbare Felder umfassen name, languages, gender, age, tags und description. Das ursprüngliche Audiosample kann jedoch nicht geändert werden. Wenn Sie das Audio ändern möchten, müssen Sie eine neue Stimme erstellen. In der Praxis kann eine schlecht aufgenommene Stimme nicht repariert werden; sie muss ersetzt werden, und Sie müssen die neue voice_id in Ihren Anwendungen propagieren.
Löschen und Abrufen des Samples
Das Löschen ist dauerhaft und unwiderruflich:
client.audio.voices.delete(voice_id="your-voice-id")
print("Stimme gelöscht")
Nach dem Löschen wird jede Generierungsanfrage, die diese voice_id verwendet, fehlschlagen. Ein klassisches Albtraumszenario: Ein Entwickler bereinigt Teststimmen, löscht versehentlich eine, die tatsächlich den Support-IVR antreibt, und der Vorfall bricht am nächsten Morgen bei der ersten eingehenden Anruf. Stellen Sie immer sicher, dass Ihre Anwendungen aktualisiert sind, bevor Sie eine Stimme in der Produktion löschen.
Sie können auch das ursprüngliche Audio herunterladen, das zur Erstellung einer Stimme verwendet wurde:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Diese Funktion hilft Ihnen, Ihre Samples zu archivieren oder die Qualität des Quellaudios zu überprüfen, wenn eine Stimme Enttäuschung bereitet. Durch Zuhören zum Original entdecken Sie oft, dass der Fehler, der während der Generierung gehört wurde, bereits in der Aufnahme vorhanden war.
Organisieren Ihres Stimmenkatalogs
Sauberes Management kostet wenig und verhindert erhebliche Verwirrung. Benennen Sie Ihre Stimmen klar mit einem Projektvorsatz, indem Sie Muster wie podcast-narrator oder app-assistant-fr verwenden, anstatt voice1 und test-final-2. Verwenden Sie Tags, um nach Anwendungsfall, Projekt oder Kunde zu kategorisieren, sodass Listen übersichtlich bleiben, wenn sie wachsen. Dokumentieren Sie voice_ids in Ihrer Anwendungskonfiguration, niemals in einer isolierten Datei auf einem Arbeitsplatzrechner. Und löschen Sie niemals eine Produktionsstimme, ohne zuvor zu überprüfen, dass sie nirgendwo mehr referenziert wird.
Kernaussagen
- Die Voices API stellt vollständige CRUD-Fähigkeiten bereit: erstellen, auflisten, abrufen, aktualisieren, löschen
- Jede Stimme erhält eine eindeutige
voice_id, die in Generierungsanfragen verwendet wird - Offset-basierte Paginierung ermöglicht die Verwaltung einer großen Anzahl von Stimmen
- Das Löschen ist dauerhaft – alle Anfragen, die diese voice_id verwenden, werden fehlschlagen
- Das ursprüngliche Audiosample kann über den Sample-Endpunkt abgerufen werden