Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Voices API

Õppetund 4 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Lõpp-punkt /v1/voices
  2. Hääle loomine
  3. Loetlemine, pärimine ja muutmine
  4. Kustutamine ja näidise hankimine
  5. Oma häälte kataloogi korrastamine
  6. Peamised punktid

Kursust uuendati 3. novembril 2026 Voxtral TTS 3 jaoks, tuginedes Migrate from Voxtral 2 juhendile ja Mistrali Text to Speech lehekülgedele: voxtral-mini-tts-2603, mis tunnistati aegunuks 31. oktoobril 2026 ja eemaldatakse 30. aprillil 2027, asendatakse näidetes mudeliga voxtral-mini-tts-3-0. Voxtral 2 eelmääratud hääled (gb_jane_neutral…) jäävad aktsepteerituks; Voxtral 3 lisab teksti sisse sildid [emotion=…] ja [pace=…], seadistuse expressiveness, kohandatud häälduse (phoneme_hints) ning toetab 35 keelt. Mistral soovitab pärast migreerimist latentsusaeg uuesti mõõta. Allikad: Migrate from Voxtral 2 · Speech generation.

Lõpp-punkt /v1/voices

Mistrali Voices API on sinu peamine sissepääs kohandatud häälte haldamiseks. See pakub täielikku CRUD-operatsioonide komplekti (Create, Read, Update, Delete), võimaldades sul hääli luua, loetleda, pärida, muuta ja kustutada. Kui oled varem töötanud standardse REST API-ga, tunned end siin nagu kodus: ükski siinne operatsioon ei tegele otseselt helitöötlusega; tegemist on puhtalt objektide kataloogi haldamisega.

Iga API kaudu loodud hääl saab unikaalse identifikaatori ehk voice_id, mida kasutad hiljem kõne genereerimisel. Pane tähele: hääled on püsivad. Kui need on loodud, jäävad need sinu kontole kättesaadavaks kuni otsese kustutamiseni. Sa ei pea iga genereerimiskorra jaoks helinäidist uuesti saatma, seega peavad sinu rakendused salvestama vaid konfiguratsiooni ühe stringi.

Hääle loomine

Loomine toimub POST päringuga lõpp-punkti /v1/voices. Saadad base64-kodeeringus helinäidise koos kirjeldavate metaandmetega:

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Kodeeri helinäidis base64-formaati
sample_audio_b64 = base64.b64encode(
    Path("sample.mp3").read_bytes()
).decode()

# Loo hääl
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 kasutamine on vajalik, kuna päring on JSON-dokument ja JSON ei saa edastada binaarseid andmeid. API tagastab objekti, mis sisaldab voice_id, mida kasutad kõigis edasistes genereerimispäringutes. Ülaltoodud näites trükime selle välja, kuid tootmiskeskkonnas peaksid selle salvestama oma konfiguratsiooni või andmebaasi.

Loetlemine, pärimine ja muutmine

Kõigi oma häälte loendi hankimiseks toetab meetod list() leheküljeldamist:

# Hangi esimesed 10 häält
voices = client.audio.voices.list(limit=10, offset=0)

for v in voices.items:
    print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")

Leheküljeldamine põhineb nihkel (offset-based): määrad elementide arvu parameetriga limit ja alguspunkti parameetriga offset. Et sirvida ka Mistrali eelmääratud hääli (prantsuse keeles Marie ehk fr_marie_neutral, briti inglise keeles Jane jne), loetleb voices.search mõlemat perekonda, eristades neid välja type põhjal: preset või custom. Teise kümne hääle lehe saamiseks kutsume meetodit välja väärtusega offset=10. See mehhanism muutub kasulikuks niipea, kui agentuur haldab hääli kümnete klientide jaoks.

Kui vajad konkreetse hääle üksikasju, tagastab get() selle täielikud metaandmed:

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

Harjumuseks peaks saama selle operatsiooni kutsumine enne suuremat genereerimistsüklit. See kinnitab, et sinu rakendusse kodeeritud voice_id viitab oodatud häälele, mitte mõne vana projekti häälele.

Saad muuta olemasoleva hääle metaandmeid, puutumata helinäidist:

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

Muudetavad väljad on name, languages, gender, age, tags ja description. Originaalset helinäidist aga muuta ei saa. Kui soovid heli muuta, pead looma uue hääle. Praktikas tähendab see, et halvasti salvestatud häält parandada ei saa – see tuleb asendada ja uus voice_id tuleb levitada kõigis sinu rakendustes.

Kustutamine ja näidise hankimine

Kustutamine on püsiv ja pöördumatu:

client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")

Pärast kustutamist ebaõnnestub iga selle voice_id-ga genereerimispäring. Klassikaline õudusstseen: arendaja koristab testhääli, kustutab kogemata hääle, mis tegelikult toidab tugiteenuse IVR-süsteemi, ja intsident avaldub järgmisel hommikul esimesel sissetuleval kõnel. Veendu alati, et sinu rakendused on uuendatud, enne kui kustutad tootmiskeskkonnas olevat häält.

Samuti saad alla laadida algse helifaili, mida hääle loomisel kasutati:

response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)

See funktsioon aitab sul oma näidiseid arhiveerida või kontrollida lähteheli kvaliteeti, kui hääl sind pettumust valmistab. Originaali kuulates avastad sageli, et genereerimisel kuuldud viga oli juba salvestises olemas.

Oma häälte kataloogi korrastamine

Puhas haldamine maksab vähe ja hoiab ära suure segaduse. Nime oma hääled selgelt, kasutades projekti prefiksi, järgides mustreid nagu podcast-narrator või app-assistant-fr, mitte voice1 ja test-final-2. Kasuta sildistamist kasutusjuhtumi, projekti või kliendi järgi, et loendid kasvades hallatavaks jääksid. Dokumenteeri voice_id-d oma rakenduse konfiguratsioonis, mitte kunagi isoleeritud failis tööjaamas. Ja ära kunagi kustuta tootmishäält, kontrollimata esmalt, et seda ei kasutataks enam kusagil.

Peamised punktid

  • Voices API pakub täielikke CRUD-võimalusi: loo, loetle, päri, uuenda, kustuta
  • Iga hääl saab unikaalse voice_id, mida kasutatakse genereerimispäringutes
  • Nihkel põhinev leheküljeldamine võimaldab hallata suurt hulka hääli
  • Kustutamine on püsiv – kõik seda voice_id-d kasutavad päringud ebaõnnestuvad
  • Originaalset helinäidist saab hankida näidise lõpp-punkti kaudu