OpenAI Realtime API

¿Qué es OpenAI Realtime API?

La OpenAI Realtime API proporciona comunicación de baja latencia entre tu aplicación y modelos que admiten de forma nativa interacciones de voz a voz. También soporta entradas multimodales —audio, imágenes y texto— y salidas multimodales —audio y texto—, lo que la hace adecuada para experiencias de voz interactivas.

Más allá de los agentes de voz, la Realtime API se puede usar para transcripción de audio en tiempo real mediante el streaming de audio a través de una conexión WebSocket. La documentación también destaca puntos de partida recomendados (como el Agents SDK for TypeScript) para flujos de trabajo de agentes de voz basados en navegador.

Características clave

• Interacciones de voz a voz de baja latencia: Diseñada para experiencias de audio conversacionales en tiempo real, no solo solicitud/respuesta.
• Entradas multimodales (audio, imágenes, texto): Permite que una sola sesión acepte diferentes tipos de entrada según el flujo de la aplicación.
• Salidas multimodales (audio y texto): Soporta devolver audio, texto o ambos como parte de la interacción.
• Múltiples métodos de conexión: Elige entre WebRTC (navegador/lado del cliente), WebSocket (servidor de nivel intermedio con baja latencia consistente) y SIP (telefonía VoIP).
• Guías de herramientas para sesiones y conversaciones: Incluye orientación sobre prompting, eventos del ciclo de vida de la conversación y gestión del comportamiento de la sesión en el servidor.
• Transcripción en tiempo real sobre WebSocket: Proporciona un camino para transcribir flujos de audio en tiempo real.

Cómo usar OpenAI Realtime API

1. Elige un método de conexión según dónde se ejecute tu app: WebRTC para uso en navegador/cliente, WebSocket para servidor/nivel intermedio o SIP para telefonía VoIP.
2. Comienza con una sesión. Para agentes de voz en navegador, la documentación recomienda usar el Agents SDK for TypeScript, que emplea WebRTC en el navegador y WebSocket en el servidor.
3. Crea e inicializa una sesión en tu código, luego conéctate usando una clave API de cliente (el ejemplo muestra RealtimeAgent y RealtimeSession con session.connect).
4. Interactúa con el modelo usando eventos. Después de conectar, usa las guías proporcionadas para prompting/steering, gestión del ciclo de vida de la conversación y (cuando sea necesario) control del lado del servidor mediante webhooks.

La documentación también menciona detalles de migración a GA (ver FAQ) que afectan la autenticación de solicitudes Realtime.

Casos de uso

• Agente de voz basado en navegador con voz a voz: Usa WebRTC (a menudo vía Agents SDK for TypeScript) para conectar un micrófono y salida de audio para conversación interactiva.
• Asistente en tiempo real respaldado por servidor: Usa una conexión WebSocket desde un nivel intermedio cuando quieras redes de baja latencia consistente y manejo centralizado de sesiones.
• Integración VoIP/telefonía: Conéctate vía SIP cuando tu despliegue objetivo sea un entorno de telefonía en lugar de un navegador web.
• Transcripción de audio en tiempo real: Envía audio en streaming a un flujo de transcripción Realtime sobre WebSocket para recibir resultados de transcripción mientras se envía el audio.
• Interacción multimodal: Acepta audio junto con imágenes y texto en una sola sesión en tiempo real, luego devuelve audio, texto o ambos.

Preguntas frecuentes

¿Necesito el encabezado beta al usar la Realtime API GA?

Para solicitudes GA, la documentación indica que el encabezado OpenAI-Beta: realtime=v1 debe eliminarse. Si deseas conservar el comportamiento beta, continúa incluyendo ese encabezado.

¿Cómo genero credenciales para sesiones Realtime del lado del cliente (navegador)?

En la interfaz GA, la documentación describe un único endpoint REST —POST /v1/realtime/client_secrets— para generar claves usadas para inicializar una conexión WebRTC o WebSocket desde clientes. El ejemplo muestra crear una configuración de sesión y publicarla en ese endpoint.

¿Cómo difieren WebRTC y WebSocket en dónde se ejecutan?

La documentación posiciona WebRTC como ideal para interacciones del lado del navegador/cliente, mientras que WebSocket es ideal para aplicaciones del lado del servidor de nivel intermedio con conexiones de red de baja latencia consistente.

¿Qué cambio de URL aplica a la recuperación de SDP de WebRTC?

Al inicializar una sesión WebRTC en el navegador, la documentación indica que la URL para obtener información de sesión remota vía SDP ahora es /v1/realtime/calls.

¿Puedo usar la Realtime API para transcripción sin comportamiento completo de agente de voz?

Sí. La documentación destaca específicamente la transcripción de audio en tiempo real transcribiendo flujos de audio en tiempo real sobre una conexión WebSocket.

Alternativas

• Usa el Agents SDK para TypeScript sin construir todo directamente sobre los primitivos de Realtime: Esto te mantiene enfocado en la orquestación de agentes de voz mientras aprovechas Realtime en segundo plano para conectividad en navegador (WebRTC) y servidor (WebSocket).
• Construye un pipeline de transcripción request/response en lugar de streaming: Si tu app no requiere manejo de audio en tiempo real, un flujo de transcripción no en tiempo real evita el enfoque de sesión impulsado por eventos descrito para Realtime.
• Otros enfoques de comunicación en tiempo real para voz: Si necesitas flujos específicos de telefonía, la integración basada en SIP es una opción dentro de los métodos de conexión de Realtime; de lo contrario, elige entre WebRTC (navegador) y WebSocket (servidor) según el despliegue.
• Chat multimodal con endpoints no en tiempo real: Si los requisitos de latencia son menos estrictos que “comunicación de baja latencia”, un enfoque de chat multimodal no en tiempo real puede ajustarse, aunque no seguirá el mismo flujo de sesión de streaming/eventos descrito en la documentación de Realtime.