Construye con CometAPI¿Necesitas una sola API para varios modelos?Prueba el flujo en el Playground y luego crea una clave de API cuando el modelo y el costo encajen con tu caso de uso.
Conectarse a Grok Voice 3.0 con Python, generar una respuesta hablada, enviar audio, agregar herramientas y solucionar problemas comunes de la API en tiempo real.
Deon GoodwinEquipo de investigación de modelos de IA y API
Grok Voice 3.0 es el modelo de voz a voz en tiempo real de xAI, publicado el 14 de octubre de 2026. Su nombre de modelo en la API es grok-voice-3.0; al 3 de noviembre de 2026, grok-voice-latest apunta a esta versión. El anuncio de lanzamiento indica sesiones de voz a $0.08 por minuto ($4.80 por hora). Combina conversación, manejo de interrupciones y uso de herramientas para asistentes de voz y soporte al cliente. Con Python básico, una clave de la API de xAI y la biblioteca websockets, puedes enviar un mensaje y guardar una respuesta hablada. Comienza con el ejemplo a continuación y luego agrega audio grabado, transmisión en vivo desde el micrófono y herramientas de negocio a medida que tu aplicación crezca.
Revisado para mayor claridad, atribución de fuentes y terminología API actual.
Puntos clave
Grok Voice 3.0 intercambia voz y texto en tiempo real. Tu aplicación envía y recibe eventos de sesión por WebSocket durante toda la conversación.
Tu primera prueba puede ser una única iteración de texto a audio. Una respuesta reproducible confirma que la autenticación y la generación de audio funcionan antes de añadir un micrófono.
La entrada de audio requiere un formato coincidente y un límite de turno claro. Tu aplicación puede enviar audio PCM grabado con finalización manual del turno o transmitir audio del micrófono con detección de voz del lado del servidor.
Tu aplicación controla las acciones de negocio. Valida los argumentos de la función y los permisos del usuario, ejecuta la acción aprobada y devuelve el resultado para que el agente de voz continúe.
Los clientes de navegador y móviles usan credenciales de corta duración. Tu servidor conserva la clave de API permanente y emite tokens temporales para las conexiones del cliente.
¿Qué es Grok Voice 3.0?
Grok Voice 3.0 es un modelo conversacional de voz en tiempo real desarrollado por xAI, operando bajo la marca SpaceX Super Intelligence. Acepta entrada hablada o de texto y puede devolver audio y texto dentro de una sesión en curso. El modelo está optimizado para casos de uso de agentes de voz, en lugar de servir como reemplazo directo de los modelos Grok solo de texto generales.
Los asistentes de voz tradicionales suelen encadenar reconocimiento de voz, un modelo de lenguaje y síntesis de voz. Grok Voice, en cambio, expone una sesión de voz a voz con comportamiento conversacional integrado y soporte de herramientas. Esa arquitectura puede simplificar la capa de orquestación del desarrollador, aunque las aplicaciones aún necesitan captura de audio, transporte, autorización, integraciones de negocio y monitoreo.
La definición del modelo Grok Voice 3.0 identifica texto y audio como sus modalidades de entrada y salida. Para este tutorial, el primer punto de control útil es una respuesta reproducible desde un script de Python del lado del servidor.
Funciones y capacidades clave de Grok Voice 3.0
Mantener una conversación en vivo: intercambiar voz y texto por WebSocket durante toda la sesión.
Gestionar interrupciones: usar detección de voz del lado del servidor y detener la reproducción en cola cuando la persona que llama empieza a hablar.
Usar herramientas de negocio: conectar tus propias funciones para tareas como consulta de pedidos y programación.
Estos son resultados de benchmark publicados, no garantías para tu despliegue. Prueba tus propios acentos, condiciones de ruido, herramientas y vías de escalamiento antes de usar el agente con clientes.
¿Qué necesitas antes de llamar a la API de Grok Voice 3.0?
Crea o inicia sesión en una cuenta en la xAI Console, genera una clave de API y verifica que tu cuenta tenga acceso y crédito de uso disponible. Usa una terminal local o un servidor de confianza para el ejemplo en Python.
Python 3.11 o posterior y pip disponibles en el mismo entorno.
Una clave de API válida de xAI almacenada como XAI_API_KEY.
Una conexión de red que permita conexiones WebSocket seguras salientes.
Un reproductor multimedia para abrir el archivo WAV generado.
Genera una clave en la xAI Console. Guárdala en una variable de entorno en lugar de incrustarla en la aplicación.
Configura la clave de API para la sesión actual de Bash.
export XAI_API_KEY="your_xai_api_key"
En Windows PowerShell:
Configura la clave de API para la sesión actual de PowerShell.
$env:XAI_API_KEY="your_xai_api_key"
Instala el cliente WebSocket en tu entorno de Python.
python -m pip install "websockets>=14,<18"
Ejecuta los comandos restantes en la misma sesión de terminal. Si usas un entorno virtual, actívalo antes de instalar el paquete.
¿Cómo usar la API de Grok Voice 3.0 con Python?
La API Realtime nativa usa una conexión WebSocket. A diferencia de las finalizaciones de chat solo de texto, intercambia eventos de sesión en curso y transmite fragmentos de audio mientras una conversación está en progreso.
Paso 1: Seleccionar un modelo fijo y configurar la sesión
La API acepta un nombre de modelo versionado en la URL del WebSocket. El ejemplo usa grok-voice-3.0 para que la versión solicitada sea explícita. Un evento session.update establece la voz, el formato de audio y el manejo manual del turno; espera session.updated antes de enviar el prompt.
Paso 2: Enviar texto y recolectar la respuesta hablada
Guarda el siguiente script como grok_voice_demo.py. Envía un único mensaje de texto, recolecta fragmentos de audio codificados en base64 y escribe un archivo WAV mono, 24 kHz, PCM de 16 bits. También se detiene ante errores de la API, finalización no exitosa o una respuesta que no produce audio.
Crea una respuesta hablada a partir de un mensaje de texto y guárdala como un archivo WAV.
Paso 3: Ejecutar el script y comprobar el resultado
Ejecuta el ejemplo de voz en Python.
python grok_voice_demo.py
Tras una respuesta exitosa, la terminal imprimirá Saved grok_response.wav. Abre ese archivo en un reproductor multimedia y verifica que escuchas una respuesta completa a velocidad normal. Un archivo faltante o no reproducible es motivo para inspeccionar los eventos devueltos y la configuración de audio antes de añadir más funciones.
La referencia de eventos en tiempo real describe el acuse de recibo de la sesión y el ciclo de vida de la respuesta usado aquí. El script espera todo el turno antes de escribir el archivo; una aplicación de voz interactiva debería reproducir los fragmentos de audio a medida que llegan.
¿Cómo enviar audio a Grok Voice 3.0?
Audio grabado con finalización manual del turno
Este ejemplo usa un archivo WAV mono, 24 kHz, PCM de 16 bits. Grok Voice 3.0 también admite otras tasas de muestreo PCM, μ-law, A-law y Opus. El formato real debe coincidir con la configuración de session.update. Reemplaza solo el bloque conversation.item.create en el script anterior con el fragmento a continuación. Mantén la llamada response.create siguiente y el bucle de recepción existente.
Reemplaza el bloque de mensaje de texto con una carga de audio grabado dentro de main().
with wave.open("request.wav", "rb") as source:
if (
source.getnchannels() != 1
or source.getsampwidth() != 2
or source.getframerate() != SAMPLE_RATE
or source.getcomptype() != "NONE"
):
raise ValueError("Use mono, 24 kHz, 16-bit PCM WAV audio.")
pcm = source.readframes(source.getnframes())
if len(pcm) < SAMPLE_RATE * 2 // 10:
raise ValueError("Use a spoken recording longer than 100 ms.")
for offset in range(0, len(pcm), 4800):
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(pcm[offset:offset + 4800]).decode("ascii"),
}))
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
while (await receive_event(ws)).get("type") != "input_audio_buffer.committed":
pass
Indenta este reemplazo al mismo nivel que el bloque original de mensaje de texto, dentro del contexto del WebSocket. Envía muestras PCM crudas desde el archivo WAV, no la cabecera del contenedor WAV. El primer script selecciona explícitamente el manejo manual del turno, así que confirmar el búfer y luego solicitar una respuesta son acciones separadas.
Captura de micrófono en vivo y reproducción inmediata
Para una conversación interactiva, captura audio continuamente, conviértelo al formato de entrada configurado y envía fragmentos cortos mientras un bucle de recepción separado maneja las respuestas. Selecciona server_vad para detección automática de turnos en lugar del modo manual usado en el ejemplo de archivo grabado. Evita añadir un segundo response.create cuando el servidor ya está creando la respuesta.
Ante una interrupción, detén con prontitud la reproducción de audio del asistente en cola. La cancelación de red por sí sola no elimina el sonido ya almacenado en búfer por tu aplicación. Mantén la cola de reproducción pequeña y registra cuánto audio escuchó realmente el oyente para que tu aplicación mantenga el estado de la conversación consistente.
¿Cómo añadir herramientas a un agente Grok Voice 3.0?
Las aplicaciones pueden exponer herramientas como consulta de pedidos, programación o verificación de cuentas. El agente puede interpretar una solicitud hablada compleja, llamar a una función autorizada y usar el resultado para continuar. Esto es especialmente útil cuando un cliente solicita varios cambios relacionados en una misma llamada.
La API admite funciones personalizadas y herramientas gestionadas por el servidor. Para una función personalizada, tu aplicación implementa la acción; definir una herramienta no conecta por sí solo el modelo con tu base de datos.
Declara el nombre de la función, la descripción y el esquema de argumentos JSON en session.tools.
Maneja response.function_call_arguments.done, analiza los argumentos y valida el permiso del solicitante antes de ejecutar la función.
Devuelve el resultado como un evento conversation.item.create con item.type establecido en function_call_output y el call_id correspondiente.
Envía response.create después de que se hayan enviado los resultados de las funciones requeridas. Si llegan varias llamadas juntas, devuelve todos sus resultados antes de pedir al modelo que continúe.
Comienza con una herramienta de solo lectura, como comprobar el estado de entrega de un pedido. Para acciones que cambian reservas, emiten reembolsos o realizan pedidos, aplica verificaciones de identidad, confirmación y protección contra solicitudes duplicadas en la aplicación.
¿Cómo usar Grok Voice 3.0 en aplicaciones web y móviles?
Usa credenciales efímeras para conexiones del lado del cliente. Tu servidor solicita un token de corta duración con su clave de API permanente y pasa el token al cliente. Autentica las solicitudes a tu propio endpoint de tokens y aplica límites de uso para que no se convierta en una puerta de enlace sin restricciones.
Mantén visibles en la interfaz el consentimiento del micrófono, los controles de grabación y el estado de la conexión. Gestiona explícitamente la pérdida de conexión: detén la reproducción obsoleta, informa al usuario de que la conexión se está recuperando y evita repetir acciones que podrían haberse completado ya.
¿Cómo solucionar errores comunes de la API de Grok Voice 3.0?
Fallo de autenticación: confirma que XAI_API_KEY está establecido en la terminal donde se ejecuta el script y que la clave pertenece a una cuenta con acceso. No pegues la clave en logs ni mensajes de soporte.
Argumentos inesperados de la biblioteca del cliente: verifica que pip instaló la versión de websockets solicitada en el entorno de Python utilizado para ejecutar el script.
Sin salida de audio: inspecciona eventos de error y response.done, confirma que session.updated reconoció la configuración y comprueba que se haya solicitado una respuesta para el turno manual.
Reproducción distorsionada: compara los bytes reales con el códec, la tasa de muestreo, el conteo de canales y la cabecera WAV configurados. Renombrar un archivo MP3 a WAV no lo convierte.
Timeout: comprueba el acceso a la red y el estado del servicio, luego inspecciona el último evento exitoso. Reintenta una conexión fallida por separado de cualquier acción de negocio que ya podría haberse ejecutado.
¿Cuánto deberías presupuestar para llamadas a la API de Grok Voice 3.0?
El uso de voz y las integraciones personalizadas pueden generar cargos separados. Para este tutorial, las tarifas publicadas relevantes son la sesión en tiempo real y las entradas de texto; los productos independientes de transcripción y generación de voz son servicios separados.
Sesión de voz a voz: $0.08 por minuto, equivalente a $4.80 por hora.
Entrada de texto durante una sesión de voz: $0.004 por entrada de texto.
Tarifas comprobadas el 29 de octubre de 2026. Consulta la página oficial de precios para cargos actuales.
Por ejemplo, 500 minutos facturables de sesión corresponden a $40 en cargos base de voz. Esa estimación excluye entradas de texto, herramientas opcionales, telefonía y tu propia infraestructura. Comienza con sesiones de prueba cortas y cierra conexiones inactivas cuando termine la conversación.
Conclusión
Comienza con un turno completo de la API de Grok Voice 3.0: conecta, configura la sesión, envía un mensaje, recibe audio y reproduce el resultado. Una vez que ese recorrido funcione, añade voz grabada y luego construye la captura de micrófono y la reproducción en streaming a su alrededor. Introduce herramientas de negocio solo después de que los caminos de conversación y manejo de errores sean fiables.
