API Voices
Na tej strani
Posodobitev tečaja z dne 3. novembra 2026 za Voxtral TTS 3, na podlagi vodnika Migrate from Voxtral 2 in strani Mistral Text to Speech:
voxtral-mini-tts-2603, ki je bil opuščen 31. oktobra 2026 in odstranjen 30. aprila 2027, je v primerih nadomeščen zvoxtral-mini-tts-3-0. Vnaprej določeni glasovi Voxtral 2 (gb_jane_neutral…) so še vedno sprejeti; Voxtral 3 dodaja oznake[emotion=…]in[pace=…]v besedilu, nastavitevexpressiveness, prilagojeno izgovarjavo (phoneme_hints) in 35 jezikov. Mistral priporoča ponovno merjenje zakasnitve po selitvi. Viri: Migrate from Voxtral 2 · Speech generation.
Končna točka /v1/voices
API Voices podjetja Mistral je tvoja vstopna točka za upravljanje prilagojenih glasov. Izpostavlja celoten nabor operacij CRUD (ustvari, preberi, posodobi, izbriši), kar ti omogoča ustvarjanje, naštevanje, pridobivanje, spreminjanje in brisanje glasov. Če si že kdaj delal s standardnim REST API-jem, si na znanem terenu: tukaj nič ne obdeluje zvoka neposredno; gre izključno za upravljanje kataloga objektov.
Vsak glas, ustvarjen prek API-ja, prejme edinstven identifikator, voice_id, ki ga boš kasneje uporabil za generiranje govora. Zapomni si: glasovi so trajni. Ko so enkrat ustvarjeni, ostanejo na voljo v tvojem računu, dokler jih izrecno ne izbrišeš. Zvokovnega vzorca ni treba znova pošiljati za vsako generiranje, zato morajo tvoje aplikacije v konfiguraciji shraniti le niz znakov.
Ustvarjanje glasu
Ustvarjanje poteka prek klica POST na končno točko /v1/voices. Priskrbiš zvočni vzorec, kodiran v base64, skupaj z opisnimi metapodatki:
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Encode the audio sample to base64
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Create the voice
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}")
Uporaba base64 je nujna, ker je zahtevek dokument JSON, JSON pa ne more prenašati binarnih podatkov. API vrne objekt, ki vsebuje voice_id, ki ga boš obdržal za vse zahtevke za generiranje. V zgornjem primeru ga izpišemo, v produkcijskem okolju pa ga moraš zapisati v svojo konfiguracijo ali bazo podatkov.
Naštevanje, pridobivanje in spreminjanje
Za pridobitev seznama vseh tvojih glasov metoda list() podpira oštevilčevanje strani:
# Get the first 10 voices
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
Oštevilčevanje strani temelji na zamiku (offset): število elementov določiš s limit, začetno točko pa z offset. Če želiš brskati tudi po vnaprej določenih glasovih podjetja Mistral (Marie v francoščini, fr_marie_neutral, Jane v britanski angleščini itd.), voices.search izpiše obe družini, ki ju razlikuje polje type: preset ali custom. Če želiš dobiti drugo stran z desetimi glasovi, pokliči metodo z offset=10. Ta mehanizem postane uporaben takoj, ko agencija upravlja glasove za desetine strank.
Ko potrebuješ podrobnosti o določenem glasu, get() vrne vse njegove metapodatke:
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}")
Naj bo tvoja navada, da to operacijo pokličeš pred večjim zagonom generiranja. S tem preveriš, ali voice_id, trdno kodiran v tvoji aplikaciji, kaže na pričakovani glas in ne na glas iz starega projekta.
Metapodatke obstoječega glasu lahko spremeniš, ne da bi se dotaknil zvočnega vzorca:
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}")
Polja, ki jih je mogoče spreminjati, vključujejo name, languages, gender, age, tags in description. Originalnega zvočnega vzorca pa ni mogoče spremeniti. Če želiš spremeniti zvok, moraš ustvariti nov glas. V praksi slabo posnetega glasu ni mogoče popraviti – zamenjati ga je treba, novi voice_id pa boš moral razširiti po vseh svojih aplikacijah.
Brisanje in pridobivanje vzorca
Brisanje je trajno in nepovratno:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Po brisanju bo vsak zahtevek za generiranje, ki uporablja ta voice_id, spodletel. Klasičen scenarij nočne more: razvijalec počisti testne glasove, pomotoma izbriše tistega, ki dejansko poganja podporo IVR, in incident se razkrije naslednje jutro ob prvem dohodnem klicu. Pred brisanjem glasu v produkcijskem okolju se vedno prepričaj, da so tvoje aplikacije posodobljene.
Prav tako lahko preneseš izvirni zvok, uporabljen za ustvarjanje glasu:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Ta funkcija ti pomaga arhivirati vzorce ali preveriti kakovost izvornega zvoka, če te glas razočara. Če poslušaš izvirnik, pogosto odkriješ, da je bila napaka, slišana med generiranjem, že prisotna v posnetku.
Organizacija kataloga glasov
Čisto upravljanje stane malo in preprečuje veliko zmede. Svoje glasove jasno poimenuj s predpono projekta, po vzorcih, kot so podcast-narrator ali app-assistant-fr, namesto voice1 in test-final-2. Uporabi oznake za kategorizacijo glede na primer uporabe, projekt ali stranko, kar omogoča obvladovanje seznamov, ko ti rastejo. Identifikatorje voice_id dokumentiraj v konfiguraciji svoje aplikacije, nikoli ne v osamljeni datoteki na delovni postaji. In nikoli ne izbriši produkcijskega glasu, ne da bi najprej preveril, ali se nikjer več ne sklicuje nanj.
Ključne ugotovitve
- API Voices omogoča popolne zmogljivosti CRUD: ustvari, naštej, pridobi, posodobi, izbriši
- Vsak glas prejme edinstven
voice_id, ki se uporablja v zahtevkih za generiranje - Oštevilčevanje strani na podlagi zamika ti omogoča upravljanje velikega števila glasov
- Brisanje je trajno – vsi zahtevki, ki uporabljajo ta voice_id, bodo spodleteli
- Izvirni zvočni vzorec je mogoče pridobiti prek končne točke za vzorce