Arquitectura WebSocket de la Realtime API
En esta página
Actualizado el 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos:
tts-1,tts-1-hdygpt-4o-mini-ttsdejarán de funcionar el 6 de enero de 2027 (sustituto:gpt-realtime-2.1-mini, que la guía de TTS de OpenAI indica que no es compatible con/v1/audio/speech: la migración de la síntesis de voz se traslada a la Realtime API);gpt-realtime,gpt-4o-realtimey los modelos de audio herederos el 20 de enero de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribey/v1/audio/translationsel 26 de febrero de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz a dúplex completo, GPT-Live 1 está disponible en la API desde el 10 de septiembre de 2026. Addendum 3 de noviembre de 2026: sección sobre las tres arquitecturas de voz de OpenAI (GPT-Live, Realtime API, cadena de procesamiento) y selección del transporte (WebRTC, WebSocket, SIP), basada en las guías Voice agents, Audio and voice y Getting started with the Realtime API; duración máxima de la sesión: 60 minutos (Realtime conversations).
Arquitectura WebSocket de la Realtime API
La Realtime API de OpenAI representa un cambio de paradigma fundamental en la forma de interactuar con los modelos de lenguaje. A diferencia de las API REST tradicionales, que operan bajo un ciclo de solicitud-respuesta, la Realtime API utiliza el protocolo WebSocket para establecer una conexión persistente y bidireccional entre tu aplicación y el modelo.
Esta arquitectura permite el intercambio de audio en tiempo real: envías audio, el modelo lo procesa y responde verbalmente con baja latencia, omitiendo pasos intermedios de transcripción o texto a voz. Este es uno de los bloques de construcción esenciales para los agentes de voz conversacionales y el núcleo de este curso.
Tres arquitecturas de voz en 2026
Antes de abrir un WebSocket, sitúa la Realtime API en contexto junto a otras soluciones de OpenAI. La guía Voice agents distingue tres enfoques:
| Arquitectura | Ideal para | Por qué elegirla |
|---|---|---|
| GPT-Live | Conversaciones a dúplex completo con un backend separado | El modelo de voz escucha mientras habla y delega el razonamiento y el uso de herramientas en un backend de tu elección; mantiene intacto tu agente de texto existente |
| Realtime API | Voz, razonamiento y herramientas en una única sesión | Un único modelo interpreta el audio, decide qué hacer y pronuncia la respuesta |
| Cadena de procesamiento | Control granular sobre cada paso | Transcripción, luego agente de texto, luego síntesis de voz: inspeccionas o transformas el texto entre pasos y sustituyes cada componente de forma independiente |
Para nuevas aplicaciones de conversación por voz, la página Audio and voice de OpenAI recomienda ahora comenzar con GPT-Live. La Realtime API sigue siendo el punto de partida correcto cuando el agente debe encajar en una única sesión, admitiendo interrupciones del usuario, una primera respuesta de audio rápida, turnos de palabra naturales y llamadas directas a herramientas. La cadena de procesamiento funciona mejor cuando cada paso debe permanecer visible: conservar transcripciones, aplicar reglas antes de que el agente responda o emitir voz solo tras validar la respuesta.
Este curso se centra en la Realtime API y la cadena de procesamiento, cuyos componentes (transcripción, síntesis de voz) se tratan en secciones posteriores.
WebRTC, WebSocket o SIP
Tu elección de transporte depende del origen del audio. Según la documentación: usa WebRTC para audio en el navegador, con un secreto de cliente efímero generado por tu servidor; WebSocket para tuberías de audio del lado del servidor; SIP para llamadas telefónicas. Una conexión de control del lado del servidor también permite que un backend de confianza observe y dirija una sesión multimedia. Esta lección detalla WebSocket, la forma más sencilla de entender los eventos intercambiados; en un navegador, prefiere WebRTC. Una sesión de Realtime dura como máximo 60 minutos.
WebSocket frente a REST: ¿por qué esta elección?
En una arquitectura REST tradicional, cada interacción requiere una solicitud HTTP completa: abrir una conexión TCP, negociar TLS, enviar cabeceras, esperar la respuesta y cerrar la conexión. Para el audio en tiempo real, esta sobrecarga es prohibitiva.
| Criterio | REST (Responses API) | WebSocket (Realtime API) |
|---|---|---|
| Latencia | 200–500 ms por solicitud | < 50 ms tras la conexión |
| Dirección | Solo cliente → servidor | Bidireccional simultánea |
| Conexión | Nueva para cada solicitud | Persistente (sesión) |
| Audio | Archivo completo requerido | Transmisión fragmento a fragmento |
El protocolo WebSocket mantiene un canal abierto continuamente. Una vez establecido, cliente y servidor pueden enviar mensajes en cualquier momento sin esperar a que el otro termine.
Establecimiento de una conexión WebSocket
Así es como se establece una conexión con la Realtime API en Python:
import asyncio
import websockets
import json
OPENAI_API_KEY = "sk-..."
URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
async def connect_realtime():
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(URL, additional_headers=headers) as ws:
print("Conectado a la Realtime API")
# Recibir el evento de bienvenida
response = await ws.recv()
event = json.loads(response)
print(f"Tipo: {event['type']}")
# → "session.created"
# Mantener la conexión abierta
await asyncio.Future()
asyncio.run(connect_realtime())
La URL de conexión incluye el modelo como parámetro de consulta. Desde que la API alcanzó la disponibilidad general, solo se requiere la cabecera de autenticación; la cabecera OpenAI-Beta: realtime=v1 de la fase beta ha desaparecido.
Interfaz observada el 5 de agosto de 2026 — La Realtime API evoluciona (modelos, nombres de eventos, formato de sesión): en caso de duda, consulta la documentación oficial.
Arquitectura de una aplicación Realtime
Una aplicación que utiliza la Realtime API sigue una arquitectura por capas:
Capa de audio (captura/reproducción)
Captura el micrófono y reproduce las respuestas de audio. Usa PyAudio, sounddevice o la Web Audio API en el navegador.
Capa WebSocket (transporte)
Gestiona la conexión persistente, codifica/decodifica eventos JSON y maneja las reconexiones.
Capa de aplicación (lógica de negocio)
Orquesta la conversación, gestiona el contexto, llama a herramientas y procesa resultados.
Capa de servidor (proxy opcional)
En producción, un servidor intermediario protege la clave de API y añade lógica de negocio del lado del servidor.
El papel del servidor proxy
Durante el desarrollo, puedes conectar tu aplicación directamente a la Realtime API. En producción, un servidor proxy es esencial para:
- Proteger tu clave de API — nunca la expongas en el lado del cliente
- Autenticar a tus usuarios — verifica los tokens antes de abrir la sesión
- Controlar costes — limita la duración de la sesión y el uso de tokens
- Registrar interacciones — para depuración y cumplimiento normativo
# Ejemplo simplificado de un proxy WebSocket con FastAPI
from fastapi import FastAPI, WebSocket
import websockets
app = FastAPI()
@app.websocket("/ws/realtime")
async def proxy_realtime(client_ws: WebSocket):
await client_ws.accept()
headers = {"Authorization": f"Bearer {OPENAI_API_KEY}"}
async with websockets.connect(URL, additional_headers=headers) as openai_ws:
async def forward_to_openai():
async for message in client_ws.iter_text():
await openai_ws.send(message)
async def forward_to_client():
async for message in openai_ws:
await client_ws.send_text(message)
await asyncio.gather(forward_to_openai(), forward_to_client())
Puntos clave
- Tres arquitecturas de voz en OpenAI: GPT-Live (recomendada para nuevas aplicaciones conversacionales), Realtime API (voz, razonamiento y herramientas en una sesión) y la cadena transcripción → agente → síntesis
- WebRTC para audio en navegador, WebSocket para tuberías de servidor, SIP para telefonía; las sesiones duran como máximo 60 minutos
- La Realtime API usa WebSocket para comunicación bidireccional de baja latencia
- La conexión es persistente: una única apertura para toda la sesión conversacional
- La arquitectura por capas separa audio, transporte, lógica de negocio y proxy de servidor
- En producción, un servidor proxy es esencial para la seguridad y el control de costes
- El protocolo está dirigido por eventos: cada mensaje es un objeto JSON con un campo
type