Przejdź do głównej treści
Polski— Wybierz język
Menu

Interfejs API Voices

Lekcja 4 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Punkt końcowy /v1/voices
  2. Tworzenie głosu
  3. Listowanie, pobieranie i modyfikowanie
  4. Usuwanie i pobieranie próbki
  5. Organizacja katalogu głosów
  6. Kluczowe wnioski

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 modelem voxtral-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, ustawienie expressiveness, 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_id uż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