Parametry żądania TTS
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie strony xAI Text to Speech oraz dokumentacji referencyjnej Voice API. Źródła: Text to Speech · Voice API.
Dostosuj swoją syntezę mowy
Punkt końcowy POST /v1/tts opiera się na czterech głównych parametrach w ciele żądania JSON, plus kilku ustawieniach opcjonalnych. Każdy z nich daje Ci precyzyjną kontrolę nad generowanym dźwiękiem, a ich zrozumienie pozwala dopasować syntezę do Twojego przypadku użycia.
Parametr text
Wraz z parametrem language, text jest jedynym wymaganym parametrem. Przyjmuje ciąg znaków o długości do 60 000 znaków, który może zawierać zwykły tekst lub tagi ekspresyjne (omówione w następnej sekcji).
{
"text": "Hello and welcome. Today, we're going to talk about artificial intelligence."
}
Powyżej 60 000 znaków żądanie HTTP zostanie odrzucone. W przypadku dłuższych tekstów xAI zaleca użycie protokołu WebSocket, który nie ma limitu całkowitej długości (lekcje od 9 do 12), lub podział tekstu na segmenty, których dźwięk następnie scalisz. Dokonuj podziału w naturalnych miejscach (końce zdań, akapity), aby uzyskać płynny rezultat.
Parametr voice_id
Ten parametr ustawia głos używany do syntezy. Jest opcjonalny i domyślnie przyjmuje wartość eve. Identyfikatory nie rozróżniają wielkości liter: Eve, EVE i eve są równoważne.
xAI oferuje 28 wbudowanych głosów (stan na 3 listopada 2026 r.), tyle samo co w przypadku agenta głosowego, plus głosy niestandardowe utworzone za pomocą Custom Voices API. Oto pięć oryginalnych głosów według opisu xAI:
- eve: energiczny i radosny, brytyjski akcent
- ara: ciepły i przyjazny
- rex: pewny siebie i wyraźny
- sal: gładki i zrównoważony
- leo: autorytatywny i potężny, brytyjski akcent
Pozostałe 23 głosy (carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora oraz liora) są opisane wraz z przypadkami ich użycia na stronie xAI Text to Speech; endpoint GET /v1/tts/voices zwraca aktualną listę (lekcja 3).
{
"text": "Welcome to this tutorial.",
"voice_id": "rex",
"language": "en"
}
Zgodnie z informacjami od xAI, każdy głos obsługuje każdy obsługiwany język. Wybór głosu nie wpływa na cenę, która zależy od liczby znaków.
Parametr language
Ten parametr jest wymagany. Przyjmuje kod BCP-47 lub specjalną wartość auto w celu automatycznego wykrycia języka.
Obsługiwanych jest 20 języków:
| Kod | Język | Kod | Język |
|---|---|---|---|
en | Angielski | ko | Koreański |
fr | Francuski | hi | Hindi |
de | Niemiecki | bn | Bengalski |
es-ES | Hiszpański (Hiszpania) | ar-EG | Arabski (Egipt) |
es-MX | Hiszpański (Meksyk) | ar-SA | Arabski (Arabia Saudyjska) |
pt-BR | Portugalski (Brazylia) | ar-AE | Arabski (ZEA) |
pt-PT | Portugalski (Portugalia) | tr | Turecki |
it | Włoski | id | Indonezyjski |
ru | Rosyjski | vi | Wietnamski |
zh | Chiński | ja | Japoński |
Automatyczne wykrywanie (auto) działa dobrze dla tekstów w jednym języku, ale w przypadku tekstów mieszających kilka języków, należy jawnie podać język główny.
Parametr output_format
Ten opcjonalny parametr jest obiektem JSON kontrolującym format wyjścia audio. Składa się z trzech podparametrów.
codec
Kodek ustawia format kodowania:
mp3(domyślny): format skompresowany, idealny do sieci i streaminguwav: format bezstratny, lepsza jakość, ale większe plikipcm: surowe audio bez nagłówka, przeznaczone do potoków przetwarzaniamulaw/ulaw: kodek G.711 mu-law dla telefoniialaw: kodek G.711 A-law dla telefonii
sample_rate
Częstotliwość próbkowania w hercach. Akceptowane wartości: 8000, 16000, 22050, 24000 (domyślnie), 44100, 48000.
bit_rate
Szybkość transmisji bitów w bitach na sekundę, tylko dla kodeka MP3. Akceptowane wartości: 32000, 64000, 96000, 128000 (domyślnie), 192000.
{
"text": "High-quality audio for production.",
"voice_id": "ara",
"language": "en",
"output_format": {
"codec": "wav",
"sample_rate": 48000
}
}
Parametr speed
speed ustawia prędkość odtwarzania: 1.0 to normalna prędkość (wartość domyślna), a zakres wynosi od 0.7 do 1.5. Nieco wolniejsze tempo pomaga przy gęstych treściach edukacyjnych; powyżej 1.2 zawsze odsłuchaj wynik ponownie.
Zalecane kombinacje
| Przypadek użycia | codec | sample_rate | bit_rate |
|---|---|---|---|
| Sieć / streaming | mp3 | 24000 | 128000 |
| Produkcja audio | wav | 48000 | — |
| Telefonia VoIP | mulaw | 8000 | — |
| Potok ML | pcm | 16000 | — |
Kluczowe wnioski
textilanguageto jedyne wymagane parametryvoice_idjest opcjonalny (domyślnie:eve) i nie rozróżnia wielkości literoutput_formatkontroluje kodek, częstotliwość próbkowania i szybkość transmisji bitów;speedustawia prędkość (od 0.7 do 1.5)- MP3 przy 24 kHz / 128 kbps to dobry domyślny kompromis między jakością a rozmiarem
- Do zastosowań telefonicznych użyj
mulawlubalawprzy 8 kHz