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

Rozpocznij pracę z interfejsem API Text-to-Speech

Lekcja 6 z 14 Zaktualizowano 3 listopada 2026 Średnio zaawansowani
Na tej stronie
  1. Tekst na wejściu, dźwięk na wyjściu
  2. HTTP lub WebSocket: dwa sposoby wywołania usługi
  3. Parametry żądania HTTP
  4. Wybór formatu wyjściowego
  5. Odpytywanie katalogu głosów
  6. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie stron xAI Text to Speech oraz Pricing. Źródła: Text to Speech · Pricing.

Tekst na wejściu, dźwięk na wyjściu

Interfejs API Grok Text-to-Speech robi jedną rzecz i robi ją dobrze: zamienia tekst w wysokiej jakości audio. Podczas gdy Voice Agent zarządza dialogiem, uwzględniając zmianę ról i przerwania, TTS działa wyłącznie w jednym kierunku: wysyłasz tekst, a otrzymujesz dźwięk. Ta prostota czyni go narzędziem z wyboru wszędzie tam, gdzie maszyna nie oczekuje odpowiedzi: narracja artykułów, powitania telefoniczne, lektorat do modułów e-learningowych czy powiadomienia audio.

$15
za milion znaków
20
obsługiwanych języków
28
wbudowanych głosów
60 000
maks. znaków na żądanie

HTTP lub WebSocket: dwa sposoby wywołania usługi

Tryb HTTP jest najbardziej bezpośredni. Wysyłasz żądanie POST z tekstem, a odpowiedź zawiera kompletny plik audio, domyślnie w formacie MP3:

curl -X POST "https://api.x.ai/v1/tts" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -o output.mp3 \
  -d '{
    "text": "Witamy w Corsen Academy.",
    "voice_id": "ara",
    "language": "pl"
  }'

Zwróć uwagę na parametr -o output.mp3: ciało odpowiedzi to surowe audio, a nie JSON zawierający link. Tryb ten idealnie nadaje się do generowania w tle, np. nocnych zadań wsadowych tworzących wersje audio Twoich artykułów, ponieważ nikt nie czeka przed ekranem.

Tryb WebSocket odpowiada innemu potrzebom: słyszysz dźwięk, zanim cały tekst zostanie zsyntetyzowany. Otwierasz połączenie i przekazujesz parametry w adresie URL:

wss://api.x.ai/v1/tts?language=pl&voice=ara&codec=mp3

Następnie wysyłasz tekst fragmentami za pomocą text.delta, sygnalizujesz koniec poleceniem text.done, a audio wraca jako fragmenty base64 w audio.delta. Strumieniowanie znosi limit długości obowiązujący w trybie HTTP i, co najważniejsze, pozwala syntetyzować na bieżąco, co jest kluczowe, gdy tekst jest wciąż generowany przez model.

Parametry żądania HTTP

ParametrTypWymaganyOpis
textstringTakTekst do konwersji, do 60 000 znaków
voice_idstringNieGłos do użycia (domyślnie: eve)
languagestringTakKod BCP-47 (pl, en, fr, de, …) lub auto
output_formatobjectNieKodek, częstotliwość próbkowania i bitrate
speednumberNieSzybkość odtwarzania od 0,7 do 1,5 (domyślnie: 1,0)

Dwa punkty wymagają uwagi. language jest wymagany, co często dziwi użytkowników: usługa nie zgaduje języka tekstu, chyba że wyraźnie poprosisz ją o to, używając wartości auto. Parametr voice_id korzysta z dokładnie tych samych głosów co Voice Agent (28 wbudowanych głosów na dzień 3 listopada 2026 r., w tym eve, ara, rex, sal i leo, plus Twoje głosy niestandardowe) i nie rozróżnia wielkości liter. Ta sama osoba głosowa może więc zasilać zarówno agenta konwersacyjnego, jak i nagrane treści, co warto wykorzystać dla spójności marki.

Wybór formatu wyjściowego

Pole output_format steruje kodekiem i jakością:

{
  "text": "Tekst do konwersji.",
  "voice_id": "rex",
  "language": "pl",
  "output_format": {
    "codec": "wav",
    "sample_rate": 44100
  }
}

Wybierz kodek w zależności od tego, co stanie się z plikiem dalej. mp3 nadaje się do ogólnego użytku: jest dobrze skompresowany i odtwarzany wszędzie, więc to rozsądny wybór domyślny dla strony internetowej czy podcastu. wav jest bezstratny, więc zajmuje więcej miejsca, ale jest niezbędny, gdy montażysta będzie przerabiał ścieżkę. pcm dostarcza surowe audio dla potoków przetwarzania, które nie potrzebują kontenera. Wreszcie, mulaw i alaw to kodeki telefoniczne G.711 przeznaczone dla systemów telekomunikacyjnych, które ich wymagają.

Częstotliwości próbkowania mieszczą się w zakresie od 8000 do 48 000 Hz, z wartością domyślną 24 000 Hz, co pokrywa zdecydowaną większość zastosowań. Dla MP3 bitrate wynosi od 32 000 do 192 000 bps, z domyślną wartością 128 000. Zwiększanie go do 192 000 dla mowy ludzkiej niemal nie poprawia doznań słuchowych, a powiększa pliki o jedną trzecią: zachowaj ten zapas dla treści łączących muzykę z głosem.

Odpytywanie katalogu głosów

API udostępnia dwa punkty końcowe tylko do odczytu, które uzupełniają generowanie. GET /v1/tts/voices zwraca wszystkie dostępne głosy wraz z ich metadanymi, a GET /v1/tts/voices/{voice_id} zwraca te same pola (voice_id, name, language) dla pojedynczego głosu; ton i przypadki użycia każdego głosu opisano na stronie xAI Text to Speech. Zamiast sztywno kodować nazwy głosów w interfejsie, wypełniaj swój selektor głosów na podstawie tych punktów końcowych – dzięki temu aplikacja pozostanie aktualna nawet w dniu zmiany katalogu.

Kluczowe wnioski

  • TTS konwertuje tekst na audio przez HTTP (proste) lub WebSocket (strumieniowanie)
  • Koszt to 15 USD za milion znaków, z maksimum 60 000 znaków na żądanie HTTP
  • 28 wbudowanych głosów, pięć kodeków i sześć częstotliwości próbkowania zapewnia dużą elastyczność
  • Tryb WebSocket nie ma limitu całkowitej długości tekstu (każdy delta jest ograniczony do 60 000 znaków)
  • Kod BCP-47 jest wymagany do określenia języka (lub auto dla wykrywania automatycznego)