Voices-API:n
På denna sida
Kursen uppdaterad 3 november 2026 för Voxtral TTS 3, baserat på guiden Migrate from Voxtral 2 och Mistral:s sidor om Text to Speech:
voxtral-mini-tts-2603, avvecklad 31 oktober 2026 och borttagen 30 april 2027, ersätts i exemplen medvoxtral-mini-tts-3-0. Fördefinierade röster i Voxtral 2 (gb_jane_neutral…) accepteras fortfarande; Voxtral 3 lägger till taggarna[emotion=…]och[pace=…]i texten, inställningenexpressiveness, anpassat uttal (phoneme_hints) samt stöd för 35 språk. Mistral rekommenderar att du mäter latensen på nytt efter migreringen. Källor: Migrate from Voxtral 2 · Speech generation.
Slutpunkten /v1/voices
Mistrals Voices-API är din ingångsport för att hantera anpassade röster. Det exponerar en fullständig uppsättning CRUD-operationer – Create, Read, Update, Delete – vilket låter dig skapa, lista, hämta, modifiera och radera röster. Om du tidigare har arbetat med ett vanligt REST-API befinner du dig på bekant mark: inget här handlar direkt om ljudbearbetning; detta handlar enbart om att hantera en katalog av objekt.
Varje röst som skapas via API:t tilldelas en unik identifierare, voice_id, som du senare använder för att generera tal. Kom ihåg detta: röster är beständiga. När de väl har skapats finns de kvar i ditt konto tills de uttryckligen raderas. Du behöver inte skicka med ljudexemplet vid varje generering, så dina applikationer behöver bara lagra en sträng i sin konfiguration.
Skapa en röst
Skapandet sker via ett POST-anrop till slutpunkten /v1/voices. Du tillhandahåller ett ljudexempel kodat i base64 tillsammans med beskrivande metadata:
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Koda ljudexemplet till base64
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Skapa rösten
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}")
Användning av base64 är nödvändig eftersom begäran är ett JSON-dokument, och JSON kan inte bära binär data. API:t returnerar ett objekt som innehåller voice_id som du sparar för alla genereringsbegäranden. I exemplet ovan skriver vi ut det, men i produktion bör du skriva det till din konfiguration eller databas.
Lista, hämta och modifiera
För att hämta en lista över alla dina röster stöder metoden list() paginering:
# Hämta de första 10 rösterna
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
Pagineringen är offset-baserad: du anger antalet objekt med limit och startpunkten med offset. För att även bläddra i Mistrals fördefinierade röster (Marie på franska, fr_marie_neutral, Jane på brittisk engelska etc.) listar voices.search båda familjerna, vilka särskiljs av fältet type: preset eller custom. För att hämta den andra sidan med tio röster anropar du metoden med offset=10. Denna mekanism blir användbar så snart en byrå hanterar röster för dussintals kunder.
När du behöver detaljer om en specifik röst returnerar get() dess fullständiga 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}")
Gör det till en vana att anropa denna operation innan en större genereringskörning. Detta verifierar att voice_id som är hårdkodad i din applikation pekar på rätt röst och inte på en från ett gammalt projekt.
Du kan modifiera metadata för en befintlig röst utan att röra ljudexemplet:
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}")
Fält som kan modifieras inkluderar name, languages, gender, age, tags och description. Det ursprungliga ljudexemplet kan dock inte ändras. Om du vill byta ljud måste du skapa en ny röst. I praktiken går en dåligt inspelad röst inte att laga – den måste ersättas, och du kommer att behöva distribuera den nya voice_id till dina applikationer.
Radera och hämta exemplet
Radering är permanent och oåterkallelig:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Efter radering kommer alla genereringsbegäranden som använder den voice_id att misslyckas. Ett klassiskt mardrömsscenario: en utvecklare städar bort teströster, råkar radera en som faktiskt driver support-IVR:n, och incidenten uppdagas nästa morgon vid det första inkommande samtalet. Se alltid till att dina applikationer är uppdaterade innan du raderar en röst i produktion.
Du kan också ladda ner det ursprungliga ljud som användes för att skapa en röst:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Denna funktion hjälper dig att arkivera dina exempel eller verifiera kvaliteten på källjudet om en röst disappointar dig. Genom att lyssna på originalet upptäcker du ofta att felet som hördes under genereringen redan fanns i inspelningen.
Organisera din röstkatalog
Ren hantering kostar lite och förhindrar stor förvirring. Namnge dina röster tydligt med ett projektprefix, enligt mönster som podcast-narrator eller app-assistant-fr, snarare än voice1 och test-final-2. Använd taggar för att kategorisera efter användningsområde, projekt eller kund, vilket gör listorna hanterbara när de växer. Dokumentera voice_id i din applikationskonfiguration, aldrig i en isolerad fil på en arbetsstation. Och radera aldrig en produktionsröst utan att först verifiera att den inte längre refereras till någonstans.
Viktiga punkter
- Voices-API:t exponerar fullständiga CRUD-funktioner: skapa, lista, hämta, uppdatera, radera
- Varje röst tilldelas en unik
voice_idsom används i genereringsbegäranden - Offset-baserad paginering låter dig hantera ett stort antal röster
- Radering är permanent – alla begäranden som använder den voice_id kommer att misslyckas
- Det ursprungliga ljudexemplet kan hämtas via sample-slutpunkten