Punkt końcowy POST /v1/tts
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie strony xAI Text to Speech, dokumentacji referencyjnej Voice API oraz strony Pricing. Źródła: Text to Speech · Voice API · Pricing.
Zamieniaj tekst w dźwięk dzięki Grok API
API Text-to-Speech od xAI zamienia dowolny tekst w naturalnie brzmiący dźwięk za pomocą pojedynczego wywołania HTTP. Głównym punktem wejścia jest POST /v1/tts, który przyjmuje Twój tekst i zwraca bezpośrednio binarny plik audio.
Struktura żądania
Wysyłasz żądanie POST na adres https://api.x.ai/v1/tts z ciałem w formacie JSON. Oto minimalny przykład użycia curl:
curl -X POST "https://api.x.ai/v1/tts" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, and welcome to Corsen Academy.",
"voice_id": "eve",
"language": "en"
}' \
--output audio.mp3
Serwer odpowiada bezpośrednio binarnym plikiem audio w treści odpowiedzi. Nie ma tu żadnej koperty JSON: otrzymujesz surowe bajty pliku audio.
Uwierzytelnianie
Jak w przypadku każdego punktu końcowego API xAI, dołącz swój klucz API w nagłówku Authorization w formacie Bearer:
Authorization: Bearer xai-your-api-key
Ciało żądania
Ciało JSON opiera się na czterech głównych parametrach:
text(wymagane): tekst do konwersji, do 60 000 znaków. Obsługuje tagi ekspresyjne, o których dowiesz się w kolejnych lekcjachvoice_id(opcjonalne): identyfikator głosu. Domyślnieeve. Wartości nie rozróżniają wielkości literlanguage(wymagane): kod języka w formacie BCP-47 (en,fr,de, …) lubautow celu automatycznego wykryciaoutput_format(opcjonalne): obiekt konfigurujący kodek, częstotliwość próbkowania i bitrate
Żądanie uzupełniają inne ustawienia, wszystkie opcjonalne: speed (szybkość odtwarzania od 0,7 do 1,5, domyślnie 1,0), replace (tabela podstawień, która koryguje wymowę słowa bez zmiany wysyłanego tekstu), with_timestamps (znaczniki czasu dla każdego znaku), text_normalization (rozpisywanie liczb, skrótów i symboli przed syntezą) oraz optimize_streaming_latency ("1" skraca czas oczekiwania na pierwszy fragment audio kosztem niewielkiej utraty jakości na łączeniach).
Odpowiedź HTTP
W przypadku sukcesu (status 200) serwer zwraca plik audio z typem treści odpowiadającym żądanemu formatowi:
audio/mpegdla MP3 (domyślnie)audio/wavdla WAVaudio/pcmdla surowego PCMaudio/basicdla G.711 μ-law (mulaw)audio/alawdla G.711 A-law (alaw)
Odpowiedź nie zawiera metadanych, wyłącznie bajty audio. Jedynym wyjątkiem jest with_timestamps: wtedy odpowiedź staje się obiektem JSON zawierającym audio w formacie base64, jego czas trwania oraz znacznik czasu dla każdego znaku. Możesz zapisać odpowiedź bezpośrednio do pliku lub strumieniować ją do odtwarzacza audio.
Przykład w Pythonie
import requests
response = requests.post(
"https://api.x.ai/v1/tts",
headers={"Authorization": f"Bearer {api_key}"},
json={
"text": "Here's an example of speech synthesis.",
"voice_id": "rex",
"language": "en"
}
)
with open("output.mp3", "wb") as f:
f.write(response.content)
Przykład w JavaScript (Node.js)
const response = await fetch("https://api.x.ai/v1/tts", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.XAI_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
text: "Here's an example of speech synthesis.",
voice_id: "rex",
language: "en"
})
});
const buffer = await response.arrayBuffer();
fs.writeFileSync("output.mp3", Buffer.from(buffer));
Cennik
Usługa TTS kosztuje 15 USD za milion znaków (cennik xAI na dzień 3 listopada 2026 r.). Płacisz za znaki wysłane w polu text, łącznie z tagami ekspresywnymi; tabela replace nie zmienia tej liczby. Przy średniej 1000 znaków na żądanie koszt wynosi około 0,015 USD za wywołanie.
Kluczowe wnioski
- Punkt końcowy
POST /v1/ttsto główne wejście do syntezy mowy - Odpowiedź to binarny plik audio, a nie JSON
- Tekst jest ograniczony do 60 000 znaków na żądanie HTTP; WebSocket nie ma limitu całkowitego
- Uwierzytelniasz się za pomocą nagłówka
Authorization: Bearer - Koszt to 15 USD za milion znaków