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

Punkt końcowy POST /v1/tts

Lekcja 1 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Zamieniaj tekst w dźwięk dzięki Grok API
  2. Struktura żądania
  3. Odpowiedź HTTP
  4. Cennik
  5. Kluczowe wnioski

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.

60,000
Maksymalna liczba znaków na żądanie
28
Wbudowane głosy
20
Obsługiwane języki
$15
Za milion znaków

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 lekcjach
  • voice_id (opcjonalne): identyfikator głosu. Domyślnie eve. Wartości nie rozróżniają wielkości liter
  • language (wymagane): kod języka w formacie BCP-47 (en, fr, de, …) lub auto w celu automatycznego wykrycia
  • output_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/mpeg dla MP3 (domyślnie)
  • audio/wav dla WAV
  • audio/pcm dla surowego PCM
  • audio/basic dla G.711 μ-law (mulaw)
  • audio/alaw dla 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/tts to 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