Voices API
Tällä sivulla
Kurssi päivitetty 3. marraskuuta 2026 Voxtral TTS 3:ta varten perustuen Migrate from Voxtral 2 -oppaaseen ja Mistralin Text to Speech -sivuihin:
voxtral-mini-tts-2603, joka on vanhentunut 31. lokakuuta 2026 ja poistettu 30. huhtikuuta 2027, on korvattu esimerkeissä mallillavoxtral-mini-tts-3-0. Voxtral 2:n esiasetetyt äänet (gb_jane_neutral…) ovat edelleen tuettuja; Voxtral 3 lisää tekstiin[emotion=…]- ja[pace=…]-tagit,expressiveness-asetuksen, mukautetun ääntämisen (phoneme_hints) sekä tuki 35 kielelle. Mistral suosittelee viiveen uudelleenmittausta siirtymän jälkeen. Lähteet: Migrate from Voxtral 2 · Speech generation.
/v1/voices-päätepiste
Mistralin Voices API on sisäänkäyntisi mukautettujen äänien hallintaan. Se tarjoaa täyden valikoiman CRUD-toimintoja (Create, Read, Update, Delete), joiden avulla voit luoda, luetella, hakea, muokata ja poistaa ääniä. Jos olet aiemmin työskennellyt tavallisen REST API:n kanssa, olet tutulla maaperällä: mikään tässä ei käsittele suoraan äänenkäsittelyä; kyse on puhtaasti objektiluettelon hallinnasta.
Jokainen API:n kautta luotu ääni saa uniikin tunnisteen, voice_id:n, jota käytät myöhemmin puheen generointiin. Pidä tämä mielessä: äänet ovat pysyviä. Kun ne on luotu, ne pysyvät tililläsi saatavilla, kunnes ne nimenomaisesti poistetaan. Sinun ei tarvitse lähettää ääninäytettä uudelleen jokaista generointikertaa varten, joten sovellustesi tarvitsee vain tallentaa merkkijono konfiguraatioonsa.
Äänen luominen
Luominen tapahtuu tekemällä POST-kutsu päätepisteeseen /v1/voices. Toimitat base64-koodatun ääninäytteen sekä kuvailevat metatiedot:
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Koodaa ääninäyte base64-muotoon
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Luo ääni
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}")
Base64:n käyttö on välttämätöntä, koska pyyntö on JSON-asiakirja, eikä JSON pysty kuljettamaan binääridataa. API palauttaa objektin, joka sisältää voice_id:n, jonka säilytät kaikkia generointipyyntöjä varten. Yllä olevassa esimerkissä tulostamme sen, mutta tuotantoympäristössä sinun tulee kirjoittaa se konfiguraatioosi tai tietokantaasi.
Luettelointi, haku ja muokkaus
Hakeaksesi luettelon kaikista äänistäsi, list()-metodi tukee sivutusta:
# Hae ensimmäiset 10 ääntä
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
Sivutus perustuu offset-arvoon: määrität kohteiden määrän parametrilla limit ja aloituspisteen parametrilla offset. Selataksesi myös Mistralin esiasetettuja ääniä (Marie ranskaksi, fr_marie_neutral, Jane brittienglanniksi jne.), voices.search listaa molemmat perheet, jotka erotellaan type-kentän avulla: preset tai custom. Hakeaksesi toisen sivun, jossa on kymmenen ääntä, kutsut metodia arvolla offset=10. Tämä mekanismi käy hyödylliseksi heti, kun toimisto hallinnoi ääniä kymmenille asiakkaille.
Kun tarvitset yksityiskohtaisia tietoja tietystä äänestä, get() palauttaa sen täydelliset metatiedot:
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}")
Tee tavaksesi kutsua tätä toimintoa ennen suurta generointiajoa. Tämä varmistaa, että sovellukseesi kovakoodattu voice_id viittaa odotettuun ääneen eikä vanhan projektin ääneen.
Voit muokata olemassa olevan äänen metatietoja koskematta itse ääninäytteeseen:
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}")
Muokattavia kenttiä ovat name, languages, gender, age, tags ja description. Alkuperäistä ääninäytettä ei kuitenkaan voi muokata. Jos haluat vaihtaa äänen, sinun on luotava uusi ääni. Käytännössä huonosti nauhoitettua ääntä ei voi korjata – se on korvattava, ja sinun tulee levittää uusi voice_id kaikkiin sovelluksiisi.
Poistaminen ja näytteen hakeminen
Poistaminen on pysyvää ja peruuttamatonta:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Poistamisen jälkeen kaikki kyseistä voice_id:tä käyttävät generointipyynnöt epäonnistuvat. Klassinen painajaismaiset skenaario: kehittäjä siivoaa testääniä, poistaa vahingossa äänen, joka itse asiassa pyörittää asiakastuen IVR-järjestelmää, ja incidentti paljastuu seuraavana aamuna ensimmäisen saapuvan puhelun myötä. Varmista aina, että sovelluksesi on päivitetty ennen kuin poistat tuotantoäänen.
Voit myös ladata alkuperäisen äänen, jota käytettiin äänen luomiseen:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Tämä ominaisuus auttaa arkistoimaan näytteesi tai tarkistamaan lähdeäänlaadun, jos ääni tuottaa pettymyksen. Kuuntelemalla alkuperäistä nauhoitusta huomaat usein, että generoinnissa kuultu vika oli jo itse nauhoituksessa.
Ääniluettelosi järjestäminen
Siisti hallinta maksaa vähän ja estää merkittävää sekaannusta. Nimeä äänesi selkeästi projektietuliitteellä käyttäen malleja kuten podcast-narrator tai app-assistant-fr äläkä nimiä kuten voice1 ja test-final-2. Käytä tageja luokitteluun käyttötarkoituksen, projektin tai asiakkaan mukaan, jotta listat pysyvät hallittavina niiden kasvaessa. Dokumentoi voice_id:t sovelluksesi konfiguraatiossa, äläkoskaan erillisessä tiedostossa työasemalla. Äläkä koskaan poista tuotantoääntä varmistamatta ensin, ettei siihen viitata missään.
Keskeiset asiat
- Voices API tarjoaa täydet CRUD-toiminnot: luo, listaa, hae, päivitä, poista
- Jokainen ääni saa uniikin
voice_id:n, jota käytetään generointipyynnöissä - Offset-pohjainen sivutus mahdollistaa suuren äänimäärän hallinnan
- Poistaminen on pysyvää – kaikki kyseistä voice_id:tä käyttävät pyynnöt epäonnistuvat
- Alkuperäinen ääninäyte voidaan hakea sample-päätepisteen kautta