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

Wyświetlanie dostępnych głosów

Lekcja 3 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Programowe odkrywanie głosów
  2. GET /v1/tts/voices
  3. GET /v1/tts/voices/{voice_id}
  4. Wybór odpowiedniego głosu
  5. Implementacja wyboru głosu w aplikacji
  6. Najlepsze praktyki
  7. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie dokumentacji API Voice od xAI oraz strony Text to Speech: odpowiedź z endpointu GET /v1/tts/voices zawiera pola voice_id, name oraz language, a xAI oferuje 28 wbudowanych głosów. Źródła: Voice API · Text to Speech.

Programowe odkrywanie głosów

Zamiast sztywno kodować listę głosów w swojej aplikacji, API xAI udostępnia dedykowany endpoint do dynamicznego pobierania dostępnych głosów. Dzięki temu zawsze masz aktualne dane, gdy dodawane są nowe głosy.

GET /v1/tts/voices

Ten endpoint zwraca listę wszystkich głosów dostępnych dla usługi TTS. Nie wymaga żadnych parametrów w ciele żądania.

curl -X GET "https://api.x.ai/v1/tts/voices" \
  -H "Authorization: Bearer $XAI_API_KEY"

Odpowiedź to obiekt JSON zawierający tablicę voices. Zgodnie z dokumentacją API każdy głos posiada trzy pola: voice_id (małymi literami, przekazywany w żądaniach), name (nazwa wyświetlana) oraz language (kod języka, który może mieć wartość null).

Struktura odpowiedzi

{
  "voices": [
    {"voice_id": "eve", "name": "…", "language": "…"},
    {"voice_id": "ara", "name": "…", "language": "…"}
  ]
}

Wielokropki oznaczają wartości, których dokumentacja nie podaje jako przykłady: przed oparciem się na nich wydrukuj rzeczywistą odpowiedź. Ton i przypadki użycia każdego głosu nie znajdują się w tej odpowiedzi; są opisane na stronie xAI Text to Speech.

GET /v1/tts/voices/{voice_id}

Aby uzyskać szczegóły dotyczące konkretnego głosu, dodaj jego identyfikator do ścieżki:

curl -X GET "https://api.x.ai/v1/tts/voices/rex" \
  -H "Authorization: Bearer $XAI_API_KEY"

To wywołanie zwraca te same pola (voice_id, name, language) wyłącznie dla żądanego głosu.

Wybór odpowiedniego głosu

xAI oferuje 28 wbudowanych głosów (stan na 3 listopada 2026 r.) i dla większości z nich opisuje, do czego najlepiej się nadają. Oto kilka wskazówek z tej strony:

  • Treści edukacyjne: luna, cosmo lub lumen, wymienione jako odpowiednie do edukacji
  • Obsługa klienta: carina, iris, rigel, celeste, castor, naksh lub aurora, wymienione jako odpowiednie do wsparcia
  • Reklamy i demonstracje: altair, zenith, perseus, kepler lub lumen, wymienione jako odpowiednie do reklam; eve, energetyczny i radosny, pozostaje głosem domyślnym
  • Lektorstwo i audiobooki: orion, zagan, altair, perseus lub lux
  • Wellness: carina, helios, lux lub liora

Pięć oryginalnych głosów (eve, ara, rex, sal, leo) nie ma przypisanych konkretnych przypadków użycia: xAI opisuje je jedynie jako energetyczne i radosne (akcent brytyjski), ciepłe i przyjazne, pewne i wyraźne, gładkie i zrównoważone oraz autorytatywne i potężne (akcent brytyjski).

Implementacja wyboru głosu w aplikacji

Oto przykład dynamicznego ładowania dostępnych głosów:

import requests

def get_available_voices(api_key):
    response = requests.get(
        "https://api.x.ai/v1/tts/voices",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    response.raise_for_status()
    return response.json()["voices"]

def synthesize(api_key, text, voice_id="eve", language="en"):
    voices = get_available_voices(api_key)
    valid_ids = [v["voice_id"] for v in voices]

    if voice_id.lower() not in valid_ids:
        raise ValueError(f"Unknown voice '{voice_id}'. Available: {valid_ids}")

    response = requests.post(
        "https://api.x.ai/v1/tts",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"text": text, "voice_id": voice_id, "language": language}
    )
    return response.content

Takie podejście chroni Cię przed literówkami w identyfikatorach głosów i pozwala oferować użytkownikom aktualną listę.

Najlepsze praktyki

  • Buforuj listę głosów: endpoint /v1/tts/voices nie zmienia się często, więc jedno wywołanie podczas uruchamiania aplikacji wystarczy
  • Zaoferuj podgląd: pozwól użytkownikom odsłuchać próbkę każdego głosu przed wyborem
  • Zapisz preferencje: gdy użytkownik wybierze głos, zapisz ten wybór na potrzeby przyszłych sesji
  • Testuj w języku docelowym: głos brzmiący świetnie po angielsku może inaczej brzmieć w innym języku. Zawsze testuj go w języku swojej aplikacji

Kluczowe wnioski

  • GET /v1/tts/voices wyświetla wszystkie dostępne głosy wraz z ich metadanymi
  • GET /v1/tts/voices/{voice_id} zwraca szczegóły konkretnego głosu
  • Dostępnych jest 28 wbudowanych głosów; ich ton i przypadki użycia są opisane na stronie xAI Text to Speech
  • Odpowiedź z GET /v1/tts/voices zawiera dla każdego głosu pola voice_id, name i language
  • Ładuj głosy dynamicznie, zamiast sztywno kodować ich listę