Rozhranie Voices API
Na tejto strane
Kurz aktualizovaný 3. novembra 2026 pre Voxtral TTS 3 na základe sprievodcu Migrate from Voxtral 2 a stránok Mistral Text to Speech: model
voxtral-mini-tts-2603, zastaraný 31. októbra 2026 a odstránený 30. apríla 2027, je v príkladoch nahradený modelomvoxtral-mini-tts-3-0. Preddefinované hlasy Voxtral 2 (gb_jane_neutral…) zostávajú akceptované; Voxtral 3 pridáva do textu značky[emotion=…]a[pace=…], nastavenieexpressiveness, vlastnú výslovnosť (phoneme_hints) a podporu 35 jazykov. Mistral odporúča po migrácii znovu zmerať latenciu. Zdroje: Migrate from Voxtral 2 · Speech generation.
Koncový bod /v1/voices
Rozhranie Voices API od spoločnosti Mistral je tvojím vstupným bodom pre správu vlastných hlasov. Poskytuje úplnú sadu operácií CRUD (Create, Read, Update, Delete), čo ti umožňuje hlasy vytvárať, vypisovať, získavať, upravovať a mazať. Ak si už pracoval so štandardným REST API, budeš sa tu cítiť ako doma: nič tu priamo nesúvisí so spracovaním zvuku; ide výlučne o správu katalógu objektov.
Každý hlas vytvorený prostredníctvom API dostane jedinečný identifikátor voice_id, ktorý neskôr použiješ na generovanie reči. Maj na pamäti, že hlasy sú trvalé. Po vytvorení zostávajú dostupné v tvojom účte, kým ich explicitne neodstrániš. Nemusíš znova odosielať zvukovú vzorku pri každom generovaní, takže tvoje aplikácie potrebujú vo svojej konfigurácii uložiť len reťazec.
Vytvorenie hlasu
Vytvorenie prebieha volaním metódy POST na koncovom bode /v1/voices. Poskytneš zvukovú vzorku zakódovanú v base64 spolu s popisnými metadátami:
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Zakódovanie zvukovej vzorky do base64
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Vytvorenie hlasu
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}")
Použitie base64 je nevyhnutné, pretože požiadavka je dokument JSON a JSON nedokáže prenášať binárne dáta. API vráti objekt obsahujúci voice_id, ktorý si uložíš pre všetky budúce požiadavky na generovanie. Vo vyššie uvedenom príklade ho vypisujeme, ale v produkčnom prostredí by si ho mal zapísať do svojej konfigurácie alebo databázy.
Vypisovanie, získavanie a upravovanie
Na získanie zoznamu všetkých tvojich hlasov podporuje metóda list() stránkovanie:
# Získanie prvých 10 hlasov
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
Stránkovanie je založené na ofsete: počet položiek určíš pomocou limit a počiatočný bod pomocou offset. Ak chceš prehliadať aj preddefinované hlasy od Mistralu (Marie vo francúzštine, fr_marie_neutral, Jane v britskej angličtine atď.), metóda voices.search vypíše obe rodiny, ktoré sú rozlíšené poľom type: preset alebo custom. Ak chceš získať druhú stránku desiatich hlasov, zavoláš metódu s offset=10. Tento mechanizmus sa stáva užitočným hneď, ako agentúra spravuje hlasy pre desiatky klientov.
Keď potrebuješ podrobnosti o konkrétnom hlase, metóda get() vráti jeho úplné metadáta:
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}")
Zvykni si volať túto operáciu pred každým väčším behom generovania. Overíš tak, že voice_id natvrdo zakódovaný v tvojej aplikácii odkazuje na očakávaný hlas, a nie na hlas zo starého projektu.
Metadáta existujúceho hlasu môžeš upraviť bez toho, aby si zasahoval do zvukovej vzorky:
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}")
Upraviteľné polia zahŕňajú name, languages, gender, age, tags a description. Pôvodnú zvukovú vzorku však zmeniť nemôžeš. Ak chceš zmeniť zvuk, musíš vytvoriť nový hlas. V praxi znamená, že zle nahraný hlas nemožno opraviť – musí byť nahradený a nový voice_id budeš musieť preniesť do všetkých svojich aplikácií.
Mazanie a získavanie vzorky
Vymazanie je trvalé a nezvratné:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Po vymazaní zlyhá každá požiadavka na generovanie používajúca tento voice_id. Klasický nočný morou scenár: vývojár uprace testovacie hlasy, omylom vymaže ten, ktorý práve poháňa IVR systém podpory, a incident vyjde najavo nasledujúce ráno pri prvom prichádzajúcom hovore. Pred vymazaním hlasu v produkčnom prostredí sa vždy uisti, že sú tvoje aplikácie aktualizované.
Môžeš si tiež stiahnuť pôvodné audio použité na vytvorenie hlasu:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Táto funkcia ti pomôže archivovať tvoje vzorky alebo overiť kvalitu zdrojového audia, ak ťa hlas sklame. Po vypočutí originálu často zistíš, že chyba počutá počas generovania bola prítomná už v samotnom nahrávaní.
Organizácia katalógu hlasov
Čistá správa stojí málo a predchádza veľkým zmätkom. Pomenuj svoje hlasy jasne s prefixom projektu, podľa vzorov ako podcast-narrator alebo app-assistant-fr, namiesto voice1 a test-final-2. Používaj tagy na kategorizáciu podľa prípadu použitia, projektu alebo klienta, aby boli zoznamy prehľadné aj pri ich raste. Dokumentuj voice_id v konfigurácii svojej aplikácie, nikdy nie v izolovanom súbore na pracovnej stanici. A nikdy nemaž produkčný hlas bez predchádzajúceho overenia, že už nikde nie je odkazovaný.
Kľúčové poznatky
- Rozhranie Voices API poskytuje plné možnosti CRUD: vytvorenie, výpis, získanie, aktualizácia, vymazanie
- Každý hlas dostane jedinečný
voice_idpoužívaný v požiadavkách na generovanie - Stránkovanie založené na ofsete ti umožňuje spravovať veľké množstvo hlasov
- Vymazanie je trvalé – všetky požiadavky používajúce daný voice_id zlyhajú
- Pôvodnú zvukovú vzorku je možné získať späť prostredníctvom koncového bodu pre vzorky