Conexiunea WebSocket TTS
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza paginii xAI Text to Speech: delte de până la 60.000 de caractere, fără timeout al conexiunii și un „permis de sesiune“ de 600 de secunde. Sursă: Text to Speech.
Sinteza vocală în timp real prin WebSocket
API-ul Grok TTS oferă un mod WebSocket pentru transmiterea în flux (streaming) a sintezei vocale. Spre deosebire de modul HTTP unar, care așteaptă finalizarea procesării pentru a returna fișierul audio complet, WebSocket trimite fragmente audio pe măsură ce sunt generate. Este ideal pentru aplicațiile interactive unde latența percepută trebuie să fie cât mai redusă posibil.
Endpoint WebSocket
Vă conectați la wss://api.x.ai/v1/tts. Parametrii de configurare se transmit în șirul de interogare (query string) al conexiunii inițiale.
Parametri de conexiune
| Parametru | Obligatoriu | Implicit | Descriere |
|---|---|---|---|
language | Da | — | Cod BCP-47 sau auto |
voice | Nu | — | ID-ul unei voci integrate sau personalizate |
codec | Nu | mp3 | mp3, wav, pcm, mulaw (sau ulaw), alaw |
sample_rate | Nu | 24000 | Frecvența de eșantionare |
bit_rate | Nu | 128000 | Rata de biți (doar pentru MP3) |
URL complet de conexiune
wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3&sample_rate=24000
Deschiderea conexiunii
În JavaScript (browser sau Node.js)
const ws = new WebSocket(
"wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
{
headers: {
"Authorization": `Bearer ${API_KEY}`
}
}
);
ws.onopen = () => {
console.log("Conexiune TTS stabilită");
};
ws.onerror = (error) => {
console.error("Eroare WebSocket:", error);
};
Important: într-un browser, API-ul nativ WebSocket nu suportă antete (headers) personalizate. Va trebui să treceți prin backend-ul dumneavoastră pentru conexiune (consultați lecția despre producție).
În Python cu websockets
import asyncio
import websockets
import json
async def connect_tts():
uri = "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3"
headers = {"Authorization": f"Bearer {api_key}"}
async with websockets.connect(uri, additional_headers=headers) as ws:
print("Conexiune TTS stabilită")
# Trimiteți textul și primiți audio...
Gestionarea sesiunii
Durata de viață
Pagina xAI Text to Speech menționează două aspecte pe care trebuie să le analizați împreună: conexiunea WebSocket nu are un timeout pentru cereri (rămâne deschisă), iar „permisul de sesiune“ are o durată de viață de 600 de secunde, fără ca pagina să explice ce se întâmplă la expirarea acestuia. Pentru siguranță, aplicația dumneavoastră ar trebui să:
- Detecteze când se închide conexiunea
- Se reconecteze automat dacă este necesar
- Reia trimiterea textului de unde a rămas
Sesiuni concurente
Conform paginii Text to Speech, echipa dumneavoastră este limitată la 50 de sesiuni WebSocket concurente (pagina Rate limits numără sesiunile TTS pe niveluri, începând de la 100). Dincolo de această limită, noile conexiuni sunt refuzate. Gestionați un pool de conexiuni pentru aplicațiile cu trafic ridicat.
Mai multe texte pe o singură conexiune
Spre deosebire de modul HTTP unar, unde cererile expiră după 15 minute, conexiunea rămâne deschisă după fiecare audio.done: puteți trimite un text după altul fără a vă reconecta și puteți anula textul curent cu text.clear (lecția 10).
HTTP unar versus WebSocket
| Aspect | HTTP unar | WebSocket |
|---|---|---|
| Latență | Audio complet după procesare | Primii octeți imediat |
| Text maxim | 60.000 de caractere per cerere | Nelimitat (delte de max. 60.000) |
| Timeout | 15 minute | Niciunul; permis de sesiune de 600 de secunde |
| Sesiuni | N/A | 50 per echipă |
| Cazuri de utilizare | Loturi, fișiere audio | Timp real, streaming |
Când să utilizați WebSocket
WebSocket este soluția recomandată de îndată ce este implicat timpul real. Când un utilizator așteaptă un răspuns vocal imediat, de la un chatbot sau un asistent vocal, fiecare secundă de liniște înainte de primul sunet vă costă în ceea ce privește experiența percepută, iar WebSocket permite începerea redării la primele fragmente audio, înainte chiar ca generarea să se fi încheiat. Este, de asemenea, arhitectura naturală atunci când textul însuși sosește treptat: ieșirea în flux a unui LLM se conectează direct la TTS, deltă cu deltă, fără a aștepta textul complet. Și elimină constrângerea de lungime: nu există o limită globală asupra textului total, doar deltele individuale sunt limitate la 60.000 de caractere, suficient pentru a vocaliza un document întreg ca un flux continuu.
Modul HTTP unar își păstrează utilitatea oriunde timpul real nu aduce niciun avantaj: generarea de fișiere audio în loturi, procese care necesită fișierul complet înainte de a acționa (post-procesare, stocare, trimitere) și, mai simplu, orice arhitectură care preferă o interacțiune stateless în detrimentul gestionării unei conexiuni persistente.
Puncte cheie
- TTS WebSocket este disponibil la
wss://api.x.ai/v1/tts - Parametrii se transmit în șirul de interogare la conectare
- Conexiunea nu expiră de la sine, dar documentația menționează un permis de sesiune de 600 de secunde: planificați reconectarea
- Limita este de 50 de sesiuni concurente per echipă
- Textul este nelimitat (trimis în delte de până la 60.000 de caractere)
- Utilizați WebSocket pentru timp real, HTTP pentru loturi