Uso de la API en tiempo real de GPT a través de WebSockets

La API en tiempo real de Azure OpenAI GPT para voz y audio es parte de la familia de modelos GPT-4o que admite interacciones conversacionales de baja latencia, "de voz a voz".

Puede usar la API en tiempo real a través de WebRTC, SIP o WebSocket para enviar la entrada de audio al modelo y recibir respuestas de audio en tiempo real.

Siga las instrucciones de este artículo para empezar a trabajar con la API en tiempo real a través de WebSockets. Use la API en tiempo real a través de WebSockets en escenarios de servidor a servidor en los que la latencia baja no es un requisito.

Propina

En la mayoría de los casos, use la API en tiempo real a través de WebRTC para el streaming de audio en tiempo real en aplicaciones del lado cliente, como una aplicación web o una aplicación móvil. WebRTC está diseñado para streaming de audio en tiempo real y de baja latencia y es la mejor opción para la mayoría de los escenarios.

Use la tabla siguiente para ayudarle a elegir el protocolo adecuado para su escenario:

Protocolo Ideal para Latencia Complejidad
WebRTC Aplicaciones del lado cliente (web, móvil) Más bajo (~50-100 ms) Superior
WebSocket Procesamiento por lotes de servidor a servidor Moderado (~100-300 ms) Inferior
SIP Integración de telefonía Varía Máximo

Requisitos previos

Para poder usar el audio en tiempo real de GPT, necesita lo siguiente:

  • Una suscripción Azure. Cree uno gratis.
  • Un recurso Microsoft Foundry. Cree el recurso en una de las regiones admitidas. Para conocer los pasos de configuración, consulte Crear un recurso de Microsoft Foundry.
  • Implementación de un modelo en tiempo real de GPT en una región admitida, tal como se describe en la sección modelos admitidos de este artículo.
    • En el portal de Foundry, cargue el proyecto. Seleccione Compilar en el menú superior derecho y, a continuación, seleccione la pestaña Modelos en el panel izquierdo y seleccione Implementar un modelo base. Busque el modelo que quiera y seleccione Implementar en la página del modelo.
  • Bibliotecas necesarias:
    • Python: pip install websockets azure-identity
    • JavaScript/Node.js: npm install ws @azure/identity

Modelos admitidos

Los modelos en tiempo real de GPT están disponibles para implementaciones globales en las regiones Este de EE. UU. 2 y Centro de Suecia.

  • gpt-4o-mini-realtime-preview (2024-12-17)
  • gpt-4o-realtime-preview (2024-12-17)
  • gpt-realtime (2025-08-28)
  • gpt-realtime-mini (2025-10-06)
  • gpt-realtime-mini (2025-12-15)
  • gpt-realtime-1.5 (2026-02-23)

Para obtener más información sobre los modelos admitidos, consulte la documentación sobre modelos y versiones.

Conexión y autenticación

La API en tiempo real (a través de /realtime) se basa en la API de WebSockets para facilitar la comunicación de streaming completamente asincrónica entre el usuario final y el modelo.

Se accede a la API en Tiempo Real a través de una conexión WebSocket segura al punto de conexión de /realtime del recurso de OpenAI de Azure.

Puede construir un URI de solicitud completa mediante la concatenación:

  • Protocolo WebSocket seguro (wss://).
  • El nombre de host del punto de conexión de recursos de OpenAI de Azure, por ejemplo, my-aoai-resource.openai.azure.com
  • La ruta de acceso de API: openai/v1/realtime para disponibilidad general o openai/realtime para la versión preliminar.
  • Parámetro model de cadena de consulta con el nombre de la implementación de su modelo gpt-realtime, gpt-realtime-1.5 o gpt-realtime-mini.
  • (Solo versión preliminar) Parámetro api-version de cadena de consulta para una versión de API compatible, como 2025-04-01-preview y un deployment parámetro de consulta en lugar de model.

El ejemplo siguiente es un URI de solicitud bien construido /realtime :

wss://my-eastus2-openai-resource.openai.azure.com/openai/v1/realtime?model=gpt-realtime-deployment-name

Nota

La API GA usa la /openai/v1/realtime ruta de acceso con model= como parámetro de consulta. La API de versión preliminar usa /openai/realtime con los parámetros api-version= y deployment=. El uso de la ruta de acceso incorrecta o la combinación de formatos de disponibilidad general y vista previa produce un error 404.

Para autenticarse:

  • Microsoft Entra (recomendado): use la autenticación basada en tokens con la API de /realtime para un recurso de OpenAI de Azure con la identidad administrada habilitada. Aplique un token de autenticación recuperado usando un token Bearer en el encabezado Authorization.
  • Clave de API: api-key se puede proporcionar de una de estas dos maneras:
    • Usar un api-key encabezado de conexión en la conexión antes del enlace. Esta opción no está disponible en un entorno del explorador.
    • Uso de un api-key parámetro de cadena de consulta en el URI de solicitud. Los parámetros de cadena de consulta se cifran al usar HTTPS/WSS.

API en tiempo real a través de la arquitectura de WebSockets

Una vez establecida y autenticada la sesión /realtime de conexión de WebSocket, la interacción funcional tiene lugar a través de eventos para enviar y recibir mensajes de WebSocket. Cada uno de estos eventos toma la forma de un objeto JSON.

Diagrama de la secuencia de conexión y autenticación de api en tiempo real.

Los eventos se pueden enviar y recibir en paralelo y las aplicaciones deben controlarlos de forma simultánea y asincrónica.

  • Un emisor de llamadas del lado del cliente establece una conexión a /realtime, lo que inicia un nuevo session.
  • Un session crea automáticamente un conversation por defecto. No se admiten varias conversaciones simultáneas.
  • conversation Acumula las señales de entrada hasta que se inicia un response, ya sea a través de un evento directo por el llamante o automáticamente por detector de actividad de voz (VAD).
  • Cada response consta de uno o más items, que pueden encapsular mensajes, llamadas de función y otra información.
  • Cada mensaje item tiene content_part, lo que permite representar varias modalidades (texto y audio) en un solo elemento.
  • session Administra la configuración del manejo de la entrada del usuario (por ejemplo, audio de usuario) y el manejo de la generación de salida común.
  • Cada acción iniciada por el llamador response.create puede modificar parte del comportamiento de salida response, si lo desea.
  • Los mensajes creados por el item servidor y el content_part se pueden rellenar de forma asincrónica y en paralelo. Recibir simultáneamente información de audio, texto y función de manera cíclica o en modo ciclo rotativo, por ejemplo.

Pruebe el inicio rápido

Ahora que ha realizado los pasos anteriores, puede seguir las instrucciones del inicio rápido de la API en tiempo real para empezar a trabajar con la API en tiempo real a través de WebSockets.

Contenido relacionado

  • Last updated on