Interfejs API Voices
Na tej stronie
Kurs zaktualizowano 3 listopada 2026 r. dla Voxtral TTS 3, na podstawie przewodnika Migrate from Voxtral 2 oraz stron Mistral dotyczących Text to Speech: model
voxtral-mini-tts-2603, wycofany 31 października 2026 r. i usunięty 30 kwietnia 2027 r., został zastąpiony w przykładach modelemvoxtral-mini-tts-3-0. Predefiniowane głosy Voxtral 2 (gb_jane_neutral…) są nadal obsługiwane; Voxtral 3 wprowadza tagi[emotion=…]i[pace=…]w tekście, ustawienieexpressiveness, niestandardową wymowę (phoneme_hints) oraz obsługę 35 języków. Mistral zaleca ponowne zmierzenie opóźnień po migracji. Źródła: Migrate from Voxtral 2 · Speech generation.
Punkt końcowy /v1/voices
Interfejs API Voices od Mistral to Twoja brama do zarządzania niestandardowymi głosami. Udostępnia pełen zestaw operacji CRUD (Create, Read, Update, Delete), pozwalając Ci tworzyć, listować, pobierać, modyfikować i usuwać głosy. Jeśli miałeś już do czynienia ze standardowym interfejsem REST API, czujesz się jak w domu: nic tutaj nie dotyczy bezpośrednio przetwarzania dźwięku; chodzi wyłącznie o zarządzanie katalogiem obiektów.
Każdy głos utworzony przez API otrzymuje unikalny identyfikator, voice_id, którego użyjesz później do generowania mowy. Zapamiętaj to dobrze: głosy są trwałe. Po utworzeniu pozostają dostępne na Twoim koncie aż do momentu ich explicitnego usunięcia. Nie musisz wysyłać próbki dźwiękowej przy każdym generowaniu, więc Twoje aplikacje muszą przechowywać w konfiguracji jedynie ciąg znaków.
Tworzenie głosu
Tworzenie odbywa się poprzez wywołanie POST do punktu końcowego /v1/voices. Dostarczasz próbkę dźwiękową zakodowaną w formacie base64 wraz z opisowymi metadanymi:
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}")
Użycie kodowania base64 jest konieczne, ponieważ żądanie jest dokumentem JSON, a JSON nie może przenosić danych binarnych. API zwraca obiekt zawierający voice_id, który zachowasz do wszystkich żądań generowania. W powyższym przykładzie go wypisujemy, ale w środowisku produkcyjnym powinieneś zapisać go w swojej konfiguracji lub bazie danych.
Listowanie, pobieranie i modyfikowanie
Aby pobrać listę wszystkich swoich głosów, metoda list() obsługuje stronicowanie:
# 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})")
Stronicowanie opiera się na przesunięciu (offset): określasz liczbę elementów za pomocą limit, a punkt startowy za pomocą offset. Aby przeglądać również predefiniowane głosy Mistral (Marie po francusku, fr_marie_neutral, Jane po brytyjsku angielsku itp.), funkcja voices.search wyświetla obie rodziny, rozróżniane przez pole type: preset lub custom. Aby uzyskać drugą stronę dziesięciu głosów, wywołujesz metodę z parametrem offset=10. Mechanizm ten staje się przydatny, gdy agencja zarządza głosami dla dziesiątek klientów.
Gdy potrzebujesz szczegółów dotyczących konkretnego głosu, metoda get() zwraca jego pełne metadane:
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}")
Wyrób sobie nawyk wywoływania tej operacji przed głównym uruchomieniem generowania. Pozwala to zweryfikować, czy voice_id zakodowany na sztywno w Twojej aplikacji wskazuje na oczekiwany głos, a nie na głos ze starego projektu.
Możesz zmodyfikować metadane istniejącego głosu bez dotykania próbki dźwiękowej:
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}")
Pola podlegające modyfikacji to name, languages, gender, age, tags oraz description. Oryginalnej próbki dźwiękowej nie można jednak zmienić. Jeśli chcesz zmienić dźwięk, musisz utworzyć nowy głos. W praktyce źle nagrany głos nie naprawi się sam – trzeba go zastąpić, a następnie rozprowadzić nowy voice_id we wszystkich swoich aplikacjach.
Usuwanie i pobieranie próbki
Usunięcie jest trwałe i nieodwracalne:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Po usunięciu każde żądanie generowania używające tego voice_id zakończy się niepowodzeniem. Klasyczny koszmar dewelopera: czyści głosy testowe, przez pomyłkę usuwa ten, który faktycznie napędza system IVR wsparcia, a incydent wychodzi na jaw następnego ranka przy pierwszym przychodzącym połączeniu. Zawsze upewnij się, że Twoje aplikacje są zaktualizowane, zanim usuniesz głos w środowisku produkcyjnym.
Możesz również pobrać oryginalny dźwięk użyty do utworzenia głosu:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Funkcja ta pomaga archiwizować próbki lub zweryfikować jakość dźwięku źródłowego, jeśli głos Cię rozczarowuje. Słuchając oryginału, często odkrywasz, że wada słyszalna podczas generowania była już obecna w nagraniu.
Organizacja katalogu głosów
Czyste zarządzanie niewiele kosztuje, a zapobiega poważnemu zamieszaniu. Nadawaj głosom przejrzyste nazwy z prefiksem projektu, stosując wzorce takie jak podcast-narrator czy app-assistant-fr, zamiast voice1 i test-final-2. Używaj tagów do kategoryzowania według przypadku użycia, projektu lub klienta, co ułatwia zarządzanie listami w miarę ich wzrostu. Dokumentuj identyfikatory voice_id w konfiguracji swojej aplikacji, nigdy w odizolowanym pliku na stacji roboczej. I nigdy nie usuwaj głosu produkcyjnego, nie upewniwszy się wcześniej, że nie jest on już nigdzie referencjonowany.
Kluczowe wnioski
- Interfejs API Voices udostępnia pełne możliwości CRUD: tworzenie, listowanie, pobieranie, aktualizowanie, usuwanie
- Każdy głos otrzymuje unikalny
voice_idużywany w żądaniach generowania - Stronicowanie oparte na przesunięciu pozwala zarządzać dużą liczbą głosów
- Usunięcie jest trwałe – wszystkie żądania używające tego voice_id zakończą się niepowodzeniem
- Oryginalną próbkę dźwiękową można pobrać poprzez punkt końcowy sample