Ir al contenido principal
Español— Elegir un idioma
Menú

El extremo WebSocket y la conexión en tiempo real

Lección 1 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. La API de agente de voz en tiempo real
  2. Establecer la conexión WebSocket
  3. Ciclo de vida de la sesión
  4. Puntos clave

Actualizado el 3 de noviembre de 2026, según las páginas de xAI Speech to Speech, Pricing y Rate limits: 0,08 $ por minuto, sesiones simultáneas por nivel y grok-voice-3.0 como modelo actual. Fuentes: Speech to Speech · Pricing · Rate limits.

La API de agente de voz en tiempo real

La API de Grok Voice Agent te permite crear agentes de voz conversacionales que hablan con tus usuarios en tiempo real. A diferencia de las API REST clásicas, que funcionan solicitud por solicitud, esta API utiliza el protocolo WebSocket para mantener abierta una conexión bidireccional persistente entre tu aplicación y los servidores de xAI.

Documentación de la API de Voice Agent

Solo hay un extremo:

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

Seleccionas el modelo con el parámetro de URL model, por ejemplo wss://api.x.ai/v1/realtime?model=grok-voice-latest. grok-voice-latest apunta a grok-voice-3.0, el modelo actual, y también es el valor predeterminado. En producción, xAI recomienda fijar una versión con nombre.

Este único extremo gestiona todo el ciclo de vida de una conversación de voz: recibir audio, detectar el habla, generar la respuesta y devolver el audio sintetizado.

WebSocket
Protocolo en tiempo real
grok-voice-3.0
Modelo actual
10
Sesiones simultáneas en el nivel de entrada
0,08 $/min
Precios

Establecer la conexión WebSocket

Para conectarte, coloca tu clave de API de xAI en la cabecera de autorización. Aquí tienes un ejemplo en JavaScript:

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

ws.on("open", () => {
  console.log("Conexión WebSocket establecida");
});

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

ws.on("close", (code, reason) => {
  console.log("Conexión cerrada:", code, reason);
});

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

En Python, puedes utilizar la 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"Evento: {event['type']}")

asyncio.run(connect())

Ciclo de vida de la sesión

Tan pronto como se abre la conexión WebSocket, el servidor envía un evento session.created confirmando que la sesión está activa. A continuación, envías un evento session.update para configurar la conversación (voz, instrucciones, herramientas, detección de turnos).

El ciclo típico es el siguiente:

  1. Conexión: abre el WebSocket con autenticación
  2. Configuración: envía session.update con tus ajustes
  3. Confirmación: recibe session.updated del servidor
  4. Conversación: intercambia eventos de audio y texto
  5. Cierre: desconecta el WebSocket limpiamente

Gestión de errores de conexión

El servidor puede cerrar o rechazar la conexión por varios motivos: un error de autenticación, haber superado el límite de sesiones simultáneas de tu nivel (10 en el nivel de entrada, hasta 200 en el más alto) o un incidente. La documentación actual no establece una duración máxima de sesión, y la reanudación de sesión (lección 4) te permite retomar una conversación tras una caída. Tu aplicación debe incluir lógica de reconexión con retroceso exponencial.

Precios verificados el 3 de noviembre de 2026. Los precios cambian a menudo: antes de presupuestar nada, consulta las tarifas actuales en la página oficial de precios de xAI.

Puntos clave

  • El extremo WebSocket wss://api.x.ai/v1/realtime es el único punto de entrada para todas las conversaciones de voz
  • Te autenticas con la cabecera Authorization: Bearer {clave de API}
  • El número de sesiones simultáneas depende de tu nivel: 10 en el nivel de entrada, hasta 200
  • El servidor envía session.created al conectarse y luego espera tu session.update para configurar la conversación
  • El precio es de 0,08 $ por minuto, o 4,80 $ por hora, más 0,004 $ por entrada de texto