Salt la conținutul principal
Română— Alege o limbă
Meniu

Endpointul WebSocket și conexiunea în timp real

Lecția 1 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. API-ul Voice Agent în timp real
  2. Deschiderea conexiunii WebSocket
  3. Ciclul de viață al sesiunii
  4. Puncte cheie

Actualizat la 3 noiembrie 2026, pe baza paginilor xAI Speech to Speech, Pricing și Rate limits: 0,08 USD pe minut, sesiuni concurente în funcție de nivel și grok-voice-3.0 ca model curent. Surse: Speech to Speech · Pricing · Rate limits.

API-ul Voice Agent în timp real

API-ul Grok Voice Agent vă permite să construiți agenți vocali conversaționali care comunică cu utilizatorii dumneavoastră în timp real. Spre deosebire de API-urile REST clasice, care funcționează cerere cu cerere, acest API utilizează protocolul WebSocket pentru a menține o conexiune bidirecțională persistentă între aplicația dumneavoastră și serverele xAI.

Documentația API Voice Agent

Există un singur endpoint:

wss://api.x.ai/v1/realtime

Selectați modelul folosind parametrul URL model, de exemplu wss://api.x.ai/v1/realtime?model=grok-voice-latest. grok-voice-latest indică spre grok-voice-3.0, modelul curent, fiind și opțiunea implicită. În producție, xAI recomandă fixarea unei versiuni denumite specifice.

Acest unic endpoint gestionează întregul ciclu de viață al unei conversații vocale: recepționarea audio, detectarea vorbirii, generarea răspunsului și trimiterea înapoi a audio-ului sintetizat.

WebSocket
Protocol în timp real
grok-voice-3.0
Model curent
10
Sesiuni concurente la nivelul de intrare
0,08 USD/min
Prețuri

Deschiderea conexiunii WebSocket

Pentru a vă conecta, includeți cheia API xAI în antetul de autorizare. Iată un exemplu în JavaScript:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer " + process.env.XAI_API_KEY
  }
});

ws.on("open", () => {
  console.log("WebSocket connection established");
});

ws.on("message", (data) => {
  const event = JSON.parse(data);
  console.log("Event received:", event.type);
});

ws.on("close", (code, reason) => {
  console.log("Connection closed:", code, reason);
});

ws.on("error", (err) => {
  console.error("WebSocket error:", err);
});

În Python, puteți utiliza biblioteca websockets:

import asyncio
import websockets
import json
import os

async def connect():
    uri = "wss://api.x.ai/v1/realtime"
    headers = {
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}"
    }

    async with websockets.connect(uri, additional_headers=headers) as ws:
        async for message in ws:
            event = json.loads(message)
            print(f"Event: {event['type']}")

asyncio.run(connect())

Ciclul de viață al sesiunii

Imediat ce conexiunea WebSocket se deschide, serverul trimite un eveniment session.created care confirmă că sesiunea este activă. Apoi, dumneavoastră trimiteți un eveniment session.update pentru a configura conversația (voce, instrucțiuni, instrumente, detectarea schimbului de replici).

Ciclul tipic arată astfel:

  1. Conexiune: deschideți WebSocket-ul cu autentificare
  2. Configurare: trimiteți session.update cu setările dumneavoastră
  3. Confirmare: primiți session.updated de la server
  4. Conversație: schimbați evenimente audio și text
  5. Închidere: deconectați WebSocket-ul corect

Gestionarea erorilor de conexiune

Serverul poate închide sau refuza conexiunea din mai multe motive: o eroare de autentificare, depășirea limitei de sesiuni concurente a nivelului dumneavoastră (10 la nivelul de intrare, până la 200 la cel mai înalt) sau un incident. Documentația curentă nu stabilește o durată maximă a sesiunii, iar reluarea sesiunii (lecția 4) vă permite să reluați o conversație după o întrerupere. Aplicația dumneavoastră ar trebui să includă o logică de reconectare cu backoff exponențial.

Prețuri verificate la 3 noiembrie 2026. Prețurile se modifică frecvent: înainte de a face orice bugetare, verificați tarifele actuale pe pagina oficială de prețuri xAI.

Puncte cheie

  • Endpointul WebSocket wss://api.x.ai/v1/realtime este singurul punct de intrare pentru toate conversațiile vocale
  • Vă autentificați folosind antetul Authorization: Bearer {cheie API}
  • Numărul de sesiuni concurente depinde de nivelul dumneavoastră: 10 la nivelul de intrare, până la 200
  • Serverul trimite session.created la conectare, apoi așteaptă session.update din partea dumneavoastră pentru a configura conversația
  • Prețul este de 0,08 USD pe minut, adică 4,80 USD pe oră, plus 0,004 USD per input de text