Tutorial de la API GPT-Realtime-2: tres pruebas, tres veredictos

Nuestro artículo de introducción a GPT-Realtime-2 repasó el lanzamiento, los benchmarks y por qué OpenAI dividió la voz en tiempo real en una familia de modelos más pequeños. Este tutorial empieza donde aquel terminaba: conectarte a la API, enviar audio y ver qué cambia en el código.

La división importa en la práctica. La Prueba 1 usa gpt-realtime-whisper para transcripción, la Prueba 2 usa gpt-realtime-translate para traducción en vivo y la Prueba 3 usa gpt-realtime-2 para un asistente por voz. El modelo principal también sirve para tareas sencillas como traducir o transcribir, pero pagarías por un nivel de razonamiento y modos de respuesta que no hacen falta: sería excesivo.

Configurar la API de GPT-Realtime-2 en Python

Antes de las pruebas, conviene separar transporte, autenticación y formato de audio. Esos detalles se mantienen casi iguales en los ejemplos. Lo que cambia a lo largo del artículo son los endpoints del modelo y los nombres de eventos, a medida que pasamos de salida de texto a voz traducida y luego a un bucle de voz completo.

Elegir entre WebRTC y WebSocket

La documentación de OpenAI da una regla sencilla: usa WebRTC para clientes en navegador y móvil, y usa WebSockets para aplicaciones del lado del servidor. WebRTC gestiona el jitter buffering y el transporte de audio. Los WebSockets tienen sentido cuando el backend ya recibe audio en crudo de un proveedor de telefonía o de una canalización de medios.

Dos rutas de transporte para la Realtime API. Imagen del autor.

Por ese motivo, las tres pruebas en Python usan WebSockets. Esa ruta muestra los nombres de los eventos directamente, así que las diferencias entre modelos se ven en el código. Para una app de navegador, usa secretos efímeros en el cliente para que tu clave de API no llegue nunca al frontend.

Entorno y paquetes de Python

Usa Python 3.9 o superior. El código completo de los cuatro scripts está disponible en github.com/KhalidAbdelaty/gpt-realtime-api. Clónalo primero y luego instala las dependencias:

git clone https://github.com/KhalidAbdelaty/gpt-realtime-api.git
cd gpt-realtime-api
pip install websocket-client sounddevice numpy python-dotenv

websocket-client gestiona el socket. sounddevice captura el audio del micrófono, numpy convierte el búfer y python-dotenv carga la clave de la API. En macOS, puede que tengas que ejecutar brew install portaudio antes de que sounddevice funcione. En Linux, instala portaudio19-dev.

Crea un archivo .env en la raíz de tu proyecto:

OPENAI_API_KEY=sk-...

Luego cárgalo en cada script:

import os
from dotenv import load_dotenv

load_dotenv()
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")

Autenticación y URL del WebSocket

Las conexiones del lado del servidor usan una cabecera Authorization: Bearer en el handshake del WebSocket. Añade OpenAI-Safety-Identifier si tu app identifica a usuarios individuales. Estas son las rutas que se usan más adelante en las pruebas:

# Agente de voz
wss://api.openai.com/v1/realtime?model=gpt-realtime-2

# Traducción
wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate

# Transcripción
wss://api.openai.com/v1/realtime?intent=transcription

Esa ruta de traducción será importante en la Prueba 2, porque es el único endpoint que no usa directamente /v1/realtime.

Prueba 1: transcripción de audio en tiempo real con GPT-Realtime-Whisper

La transcripción es un área donde es fácil sobredimensionar. Si solo necesitas texto como salida, el modelo de transcripción es suficiente.

Qué probamos

gpt-realtime-whisper recibe audio y emite deltas de transcripción. No razona, no llama a herramientas ni contesta hablando. Ese trabajo más acotado es la razón por la que se factura por duración de audio en lugar del mismo modelo por tokens que usa gpt-realtime-2. Volvemos a las tarifas en la sección de costes.

Revisión del código

El campo clave es session.type: "transcription". Eso indica a la API que se salte las respuestas del asistente y emita solo eventos de transcripción. El script completo también gestiona la captura por micrófono y los hilos. Esta es la parte que cambia el comportamiento de la sesión Realtime:

session_config = {
    "type": "session.update",
    "session": {
        "type": "transcription",
        "audio": {
            "input": {
                "format": {"type": "audio/pcm", "rate": 24000},
                "transcription": {
                    "model": "gpt-realtime-whisper",
                    "language": "en"
                },
                "turn_detection": None
            }
        }
    }
}

ws.send(json.dumps(session_config))
ws.send(json.dumps({
    "type": "input_audio_buffer.append",
    "audio": audio_b64
}))
ws.send(json.dumps({"type": "input_audio_buffer.commit"}))

Usa audio PCM16 mono a 24 kHz, codificado en base64. A diferencia de la sesión del agente de voz, el script confirma el búfer de entrada manualmente con un temporizador, en lugar de usar la detección de turnos server_vad. Las confirmaciones vacías lanzan input_audio_buffer_commit_empty, por eso el script completo solo confirma después de enviar audio real.

Los deltas de transcripción llegan palabra a palabra en tiempo real. Imagen del autor.

Comportamiento observado

En mis pruebas locales, los resultados de transcripción aparecían dentro de la ventana de commit, aproximadamente 3 a 4 segundos después de empezar a hablar. Como esta configuración depende de commits manuales y no de VAD, la latencia está ligada al intervalo de commit. 

También, cuidado con el orden: los eventos de finalización de turnos solapados pueden llegar desordenados, así que si construyes una interfaz alrededor del stream, concilia por item_id.

La transcripción se activa con commits manuales periódicos, no con detección de silencios. Imagen del autor.

Veredicto: aprobado. Para transcripción en vivo del lado del servidor, gpt-realtime-whisper cumplió lo que requería esta prueba. Aun así, probaría con micrófonos reales, acentos y ruido ambiental antes de fijar un objetivo de latencia.

Prueba 2: traducción en tiempo real con GPT-Realtime-Translate

La traducción de voz en vivo se parece al principio a la transcripción, pero el ciclo de vida de la sesión es distinto. El endpoint de traducción elimina el bucle de respuesta del asistente, lo que hace el ejemplo más corto.

Qué probamos

Las sesiones de traducción no tienen bucle de turnos del asistente ni response.create. El modelo actúa como intérprete en vivo, no como agente conversacional. Para preguntas y respuestas, herramientas o estado conversacional, en la Prueba 3 cambiamos a gpt-realtime-2.

Las sesiones de traducción usan un endpoint dedicado y separado. Imagen del autor.

El modelo admite más de 70 idiomas de entrada y 13 de salida. Fijas el idioma de destino con session.audio.output.language; la detección del idioma de origen es automática. Las limitaciones son claras: no hay prompts personalizados, ni selección de voz, ni glosarios de dominio.

Revisión del código

Como se comentó, la traducción usa la URL de WebSocket /translations. También cambian otros dos detalles: el campo de destino session.audio.output.language y el nombre del evento session.input_audio_buffer.append. Fíjate en el prefijo session.. Las sesiones de traducción lo usan aquí.

url = "wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate"

session_config = {
    "type": "session.update",
    "session": {
        "audio": {
            "output": {"language": "es"},
            "input": {
                "transcription": {"model": "gpt-realtime-whisper"},
                "noise_reduction": {"type": "near_field"}
            }
        }
    }
}

ws.send(json.dumps(session_config))
ws.send(json.dumps({
    "type": "session.input_audio_buffer.append",
    "audio": audio_b64
}))

El audio traducido llega por session.output_audio.delta, y los bytes de audio están en event["delta"], no en event["audio"]. Las transcripciones de origen y destino llegan por separado:

if event_type == "session.output_audio.delta":
    audio_out_queue.put(base64.b64decode(event["delta"]))
elif event_type == "session.input_transcript.delta":
    print("[EN]", event.get("delta", ""), end="")
elif event_type == "session.output_transcript.delta":
    print("[ES]", event.get("delta", ""), end="")

Un caso límite: si el audio de origen ya está en el idioma de destino, el modelo puede producir silencio en lugar de retransmitirlo.

Comportamiento observado

Para frases cortas de inglés a español, el audio traducido empezaba antes de que terminara el enunciado de origen. La terminal mostraba líneas entrelazadas [EN] y [ES] a medida que llegaban los deltas. En pares de idiomas más lejanos puede esperar más contexto. Pude seguir la voz traducida sin problema, pero no hay selección de voz personalizada.

Veredicto: aprobado, con matices. gpt-realtime-translate funcionó bien para traducción en vivo directa. Es menos útil cuando importan el control terminológico o la identidad sonora de marca.

Prueba 3: crear un asistente de voz con turnos e interrupciones

Esta es la prueba de gpt-realtime-2: un agente de voz que escucha, habla, mantiene el contexto y puede llamar a herramientas. También es el punto en el que el código del cliente cobra más importancia, porque la reproducción y el estado de turnos pueden desincronizarse.

Qué probamos

gpt-realtime-2 es un modelo de razonamiento voz a voz. Evita una canalización separada STT→LLM→TTS, y su ventana de contexto de 128K da margen a sesiones largas. El razonamiento se controla con reasoning.effort; empieza en low salvo que la tarea requiera más, porque ajustes más altos añaden latencia.

Revisión del código

La configuración siguiente usa semantic_vad, que se fija en señales del habla y no solo en el silencio. eagerness controla lo rápido que el modelo decide que has terminado. Fíjate en el nombre del modelo, los ajustes de salida de audio, el response.create manual y el nombre del evento de audio del asistente:

session_config = {
    "type": "session.update",
    "session": {
        "type": "realtime",
        "model": "gpt-realtime-2",
        "output_modalities": ["audio"],
        "audio": {
            "input": {
                "format": {"type": "audio/pcm", "rate": 24000},
                "transcription": {"model": "gpt-realtime-whisper", "language": "en"},
                "turn_detection": {
                    "type": "semantic_vad",
                    "eagerness": "medium",
                    "create_response": False,
                    "interrupt_response": True
                }
            },
            "output": {
                "format": {"type": "audio/pcm", "rate": 24000},
                "voice": "marin"
            }
        },
        "instructions": "You are a helpful voice assistant. Keep answers short.",
        "reasoning": {"effort": "low"}
    }
}

Cuando se completa la transcripción del usuario, el cliente crea la respuesta del asistente. El audio del asistente llega como response.output_audio.delta, no como response.audio.delta.

if event_type == "conversation.item.input_audio_transcription.completed":
    ws.send(json.dumps({"type": "response.create"}))

elif event_type == "response.output_audio.delta":
    audio_out_queue.put(base64.b64decode(event["delta"]))

Gestionar las interrupciones (barge-in)

La secuencia de interrupción es fácil de hacer mal. Cuando el usuario habla sobre el asistente, el servidor envía input_audio_buffer.speech_started. El cliente detiene la reproducción, registra cuánto audio se reprodujo y envía conversation.item.truncate con audio_end_ms para indicar dónde se cortó. Si no, el servidor sigue transcribiendo texto que el usuario nunca oyó, y el siguiente turno puede descuadrarse.

if current_response_item_id and playback_position_ms > 0:
    ws.send(json.dumps({
        "type": "conversation.item.truncate",
        "item_id": current_response_item_id,
        "content_index": 0,
        "audio_end_ms": playback_position_ms
    }))

Un problema práctico con altavoces de portátil: el micrófono puede captar la salida de audio del asistente y devolvérsela al modelo. El script de ejemplo usa MUTE_MIC_DURING_ASSISTANT = True para silenciar la entrada mientras el asistente habla y durante un breve periodo después. Ponlo en False solo si usas auriculares y quieres soportar interrupciones.

El truncado mantiene sincronizados servidor y cliente. Imagen del autor.

WebRTC y SIP gestionan más de este almacenamiento en búfer. Con la ruta WebSocket usada en este tutorial, recae en el cliente. El contador del script de ejemplo basta para una demo; en producción deberías seguir marcas de tiempo del stream de salida de audio.

Configurar preámbulos para la latencia de razonamiento

Cuando reasoning.effort está por encima de low, el silencio se vuelve notable. Puedes añadir preámbulos hablados cortos en el prompt del sistema:

# Preambles
Use a short spoken update before longer tasks.
Keep preambles under five seconds.
Skip preambles for short factual questions.

Este comportamiento está documentado para gpt-realtime-2.

Comportamiento observado

El turno de palabra funcionó con la configuración por defecto en una sala silenciosa. Con altavoces de portátil, necesité silenciar el micro; sin ello, el modelo oía su propia salida y arrancaba un bucle de eco. 

En salas más ruidosas, los ajustes de VAD y la colocación del micrófono importaron más. La memoria de la conversación se mantuvo coherente durante una prueba de diez minutos, pero no lanzaría una app más larga sin un plan de reconexión.

Veredicto: aprobado para el bucle de voz principal. gpt-realtime-2 gestionó un asistente con bajo esfuerzo de razonamiento en mi prueba. El trabajo extra está en el cliente: reproducción, gestión de interrupciones, reconexiones y llamadas a herramientas si la app las necesita.

Demo en Streamlit: los tres modelos en una sola interfaz

La app de Streamlit sitúa las pruebas tras un selector de pestañas. Te permite grabar audio, elegir un idioma de destino y comparar rutas de modelo sin tocar los scripts. Lo he dejado como app de demostración y no como vía principal de aprendizaje, porque los scripts en terminal muestran los eventos de forma más directa.

Tres modelos en una interfaz con pestañas. Imagen del autor.

El vídeo de demostración de abajo muestra las pestañas con una clave de API real. Cada pestaña usa llamadas Realtime por WebSocket reales.