Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

API Voices

Lekce 4 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Koncový bod /v1/voices
  2. Vytvoření hlasu
  3. Vypisování, získávání a úpravy
  4. Mazání a získávání vzorku
  5. Organizace katalogu hlasů
  6. Klíčové poznatky

Kurz aktualizován 3. listopadu 2026 pro Voxtral TTS 3 na základě průvodce Migrate from Voxtral 2 a stránek Mistralu Text to Speech: voxtral-mini-tts-2603, zastaralý k 31. říjnu 2026 a odstraněný k 30. dubnu 2027, je v příkladech nahrazen modelem voxtral-mini-tts-3-0. Předdefinované hlasy Voxtral 2 (gb_jane_neutral…) zůstávají podporovány; Voxtral 3 přidává do textu značky [emotion=…] a [pace=…], nastavení expressiveness, vlastní výslovnost (phoneme_hints) a podporu 35 jazyků. Mistral doporučuje po migraci znovu změřit latenci. Zdroje: Migrate from Voxtral 2 · Speech generation.

Koncový bod /v1/voices

API Voices od Mistralu je tvým vstupním bodem pro správu vlastních hlasů. Poskytuje úplnou sadu operací CRUD (Create, Read, Update, Delete), která ti umožňuje hlasy vytvářet, vypisovat, získávat, upravovat a mazat. Pokud jsi již pracoval se standardním REST API, budeš se zde cítit jako doma: nic zde přímo nezpracovává zvuk; jde čistě o správu katalogu objektů.

Každý hlas vytvořený přes API obdrží unikátní identifikátor voice_id, který později využiješ k generování řeči. Měj na paměti: hlasy jsou trvalé. Jakmile jsou vytvořeny, zůstávají ve tvém účtu dostupné, dokud je explicitně nesmažeš. Nemusíš znovu odesílat zvukový vzorek pro každé generování, takže tvoje aplikace potřebují uložit pouze řetězec ve své konfiguraci.

Vytvoření hlasu

Vytvoření probíhá prostřednictvím volání POST na koncový bod /v1/voices. Poskytneš zvukový vzorek zakódovaný v base64 spolu s popisnými metadaty:

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

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

# Zakóduj zvukový vzorek do base64
sample_audio_b64 = base64.b64encode(
    Path("sample.mp3").read_bytes()
).decode()

# Vytvoř hlas
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žití base64 je nezbytné, protože požadavek je dokument JSON a JSON neumí přenášet binární data. API vrátí objekt obsahující voice_id, který si uložíš pro všechny požadavky na generování. V příkladu výše jej vytiskneme, ale v produkčním prostředí bys jej měl zapsat do své konfigurace nebo databáze.

Vypisování, získávání a úpravy

Pro získání seznamu všech tvých hlasů podporuje metoda list() stránkování:

# Získej prvních 10 hlasů
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ánkování je založené na offsetu: počet položek určíš pomocí limit a počáteční bod pomocí offset. Pokud chceš prohlížet také předdefinované hlasy Mistralu (Marie ve francouzštině, fr_marie_neutral, Jane v britské angličtině atd.), metoda voices.search vypíše obě rodiny, rozlišené polem type: preset nebo custom. Pro získání druhé stránky deseti hlasů zavoláš metodu s offset=10. Tento mechanismus se stane užitečným, jakmile agentura spravuje hlasy pro desítky klientů.

Když potřebuješ detaily o konkrétním hlasu, metoda get() vrátí jeho úplná 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}")

Zvykni si volat tuto operaci před hlavním během generování. Ověříš tím, že voice_id natvrdo zakódovaný v tvé aplikaci odkazuje na očekávaný hlas, a ne na hlas ze starého projektu.

Metadata existujícího hlasu můžeš upravit, aniž bys zasahoval do zvukového vzorku:

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

Upravitelná pole zahrnují name, languages, gender, age, tags a description. Původní zvukový vzorek však nelze změnit. Pokud chceš změnit zvuk, musíš vytvořit nový hlas. V praxi nelze špatně nahraný hlas opravit – musí být nahrazen a budeš muset nový voice_id propagovat napříč svými aplikacemi.

Mazání a získávání vzorku

Smazání je trvalé a nevratné:

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

Po smazání selže jakýkoli požadavek na generování používající tento voice_id. Klasický noční můra scénář: vývojář uklízí testovací hlasy, omylem smaže ten, který ve skutečnosti pohání IVR podporu, a incident vyjde najevo další ráno při prvním příchozím hovoru. Před smazáním hlasu v produkci se vždy ujisti, že jsou tvoje aplikace aktualizovány.

Můžeš také stáhnout původní zvuk použitý k vytvoření hlasu:

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

Tato funkce ti pomůže archivovat tvé vzorky nebo ověřit kvalitu zdrojového zvuku, pokud tě hlas zklame. Poslechem originálu často zjistíš, že chyba slyšená během generování byla již přítomna v samotném nahrávání.

Organizace katalogu hlasů

Čistá správa stojí málo a předchází velkým zmatkům. Pojmenovávej své hlasy jasně s prefixem projektu, podle vzorů jako podcast-narrator nebo app-assistant-fr, nikoliv voice1 a test-final-2. Používej značky (tags) ke kategorizaci podle případu použití, projektu nebo klienta, aby zůstaly seznamy přehledné i při růstu. Dokumentuj voice_id ve konfiguraci své aplikace, nikdy ne v izolovaném souboru na pracovní stanici. A nikdy nemaž produkční hlas, aniž bys nejprve ověřil, že již není nikde odkazován.

Klíčové poznatky

  • API Voices poskytuje plné možnosti CRUD: vytvořit, vypsat, získat, aktualizovat, smazat
  • Každý hlas obdrží unikátní voice_id používaný v požadavcích na generování
  • Stránkování založené na offsetu umožňuje spravovat velké množství hlasů
  • Smazání je trvalé – všechny požadavky používající daný voice_id selžou
  • Původní zvukový vzorek lze získat prostřednictvím koncového bodu pro vzorky