Notas para desarrolladores sobre la Realtime API

Hace poco anunciamos nuestro modelo de voz a voz más reciente, gpt-realtime, junto con la disponibilidad general de la Realtime API y varias funciones nuevas de la API. La Realtime API y el modelo de voz a voz (s2s) pasaron a la fase de disponibilidad general (GA) con mejoras importantes en la calidad del modelo, la confiabilidad y la facilidad de uso para los desarrolladores.

Puedes conocer las nuevas funciones de la API en la documentación y en la referencia de la API. Aquí queremos destacar algunas que quizás hayas pasado por alto y explicar cuándo conviene usarlas. Si estás integrando la Realtime API en tu aplicación, esperamos que estas notas te resulten interesantes.

Mejoras del modelo

El nuevo modelo incorpora varias mejoras pensadas para las aplicaciones de voz en producción. En este artículo nos centramos en los cambios de la API. Para entender mejor el modelo y sacarle partido, te recomendamos leer el anuncio y la guía de prompts para modelos en tiempo real. Aquí destacamos algunos detalles.

Algunos consejos para usar este modelo:

• Prueba distintos prompts en el Playground de Realtime.
• Usa las voces marin o cedar para obtener la mejor calidad de voz del asistente.
• Reescribe los prompts para el nuevo modelo. Ahora sigue mejor las instrucciones, por lo que las indicaciones específicas tienen mucho más efecto.
  • Por ejemplo, el modelo anterior podía interpretar la instrucción “Di siempre X cuando ocurra Y” como una orientación general. El nuevo modelo puede seguir esa instrucción incluso en situaciones inesperadas.
  • Presta atención a las instrucciones concretas que das. Da por hecho que el modelo las seguirá.

Cambios en la interfaz de la API

Con el lanzamiento de la versión GA, actualizamos la interfaz de la Realtime API. Ahora hay dos interfaces, la beta y la GA. Recomendamos migrar las integraciones de los clientes a la interfaz GA, que ofrece nuevas funciones. La interfaz beta quedará obsoleta más adelante.

Puedes consultar la lista completa de cambios necesarios en la documentación sobre la migración de beta a GA.

Puedes acceder al nuevo modelo gpt-realtime desde la interfaz beta, aunque es posible que algunas funciones no estén disponibles. Más abajo encontrarás los detalles.

Disponibilidad de las funciones

La versión GA de la Realtime API incluye varias funciones nuevas. Solo algunas están disponibles en los modelos anteriores.

*Como el modelo beta no admite llamadas asíncronas a funciones, es posible que no gestione bien las llamadas a herramientas MCP que estén pendientes y aún no tengan un resultado. Recomendamos usar el modelo GA con MCP.

Cambios en la temperatura

En la interfaz GA eliminamos temperature como parámetro del modelo. La interfaz beta limita la temperatura al intervalo 0.6 - 1.2, con un valor predeterminado de 0.8.

Quizás te preguntes: “¿Por qué no puedo elegir libremente la temperatura para conseguir, por ejemplo, que la respuesta sea más determinista?”. Con esta arquitectura de modelo, la temperatura se comporta de otra manera. En casi todos los casos, lo más conveniente es usar el valor recomendado de 0.8.

Según lo que hemos observado, las temperaturas bajas no permiten que estas respuestas de audio sean deterministas, y las temperaturas más altas producen distorsiones en el audio. Recomendamos probar distintos prompts para controlar estos aspectos del comportamiento del modelo.

Nuevas funciones

Además de los cambios de la versión beta a la GA, agregamos varias funciones a la Realtime API.

La documentación y la referencia de la API describen todas las funciones. Aquí nos centramos en lo que conviene tener en cuenta al incorporar las nuevas funciones en una integración o migración.

Tiempos de espera por inactividad en una conversación

En algunas aplicaciones sería extraño que el usuario pasara mucho tiempo sin decir nada. Piensa en una llamada telefónica. Si dejáramos de escuchar a la persona del otro lado de la línea, le preguntaríamos si sigue ahí. Quizás el modelo no captó lo que dijo el usuario, o el usuario no sabe si el modelo sigue hablando. Agregamos una función que hace que el modelo pregunte automáticamente algo como “¿Sigues ahí?”.

Para activar esta función, establece idle_timeout_ms en la configuración de server_vad para la detección de turnos. El tiempo de espera comienza cuando termina de reproducirse el audio de la última respuesta del modelo. Para calcular cuándo vence, se suman al instante de response.done la duración de la reproducción y el tiempo de espera configurado. Si la detección de actividad de voz (VAD) no se activa durante ese período, vence el tiempo de espera.

Al vencer el tiempo de espera, el servidor envía un evento input_audio_buffer.timeout_triggered. Con ese evento se incorpora el segmento de audio vacío al historial de la conversación y se activa una respuesta del modelo. Incorporar el audio vacío permite al modelo comprobar si el usuario dijo algo durante ese período que la VAD no detectó.

Los clientes pueden activar la función de esta manera:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "You are a helpful assistant.",
    "audio": {
      "input": {
        "turn_detection": {
          "type": "server_vad",
          "idle_timeout_ms": 6000
        }
      }
    }
  }
}

Conversaciones largas y manejo del contexto

Ajustamos la forma en que la Realtime API gestiona las sesiones largas. Ten en cuenta lo siguiente:

• Las sesiones en tiempo real ahora pueden durar hasta 60 minutos. Antes, el límite era de 30 minutos.
• El modelo gpt-realtime tiene una ventana de contexto de 32 768 tokens. Cada respuesta puede consumir hasta 4096 tokens, por lo que el modelo admite un máximo de 28 672 tokens de entrada.
• Las instrucciones de la sesión y las herramientas pueden ocupar, en conjunto, hasta 16 384 tokens.
• Cuando la sesión alcanza los 28 672 tokens, el servicio trunca el contexto automáticamente al descartar mensajes. Puedes configurar este comportamiento.
• Para ahorrar tokens, el servicio GA descarta automáticamente algunos tokens de audio cuando hay una transcripción disponible.

Configuración del truncamiento

Cuando la ventana de contexto de la conversación alcanza el límite de tokens, la Realtime API empieza a truncar el contexto automáticamente. Para hacerlo, descarta los mensajes del inicio de la sesión, es decir, los más antiguos. Puedes desactivar el truncamiento con "truncation": "disabled". En ese caso, la API devuelve un error cuando una respuesta tiene demasiados tokens de entrada. La ventaja del truncamiento es que la sesión puede continuar aunque la entrada supere el tamaño que admite el modelo. La Realtime API no resume los mensajes descartados ni realiza su compactación, pero puedes implementar estas operaciones por tu cuenta.

El truncamiento tiene una desventaja: modificar los mensajes del inicio de la conversación invalida los tokens guardados mediante el almacenamiento en caché de prompts. Este mecanismo identifica el contenido que coincide exactamente al inicio de los prompts. En cada turno posterior, solo se conservan en caché los tokens que no han cambiado. Cuando el truncamiento altera el inicio de la conversación, se reduce la cantidad de tokens que se pueden almacenar en caché.

Para mitigar este efecto, implementamos una función que descarta más contenido del estrictamente necesario cada vez que se trunca el contexto. Establece la proporción de retención en 0.8 para descartar el 20 % de la ventana de contexto en lugar de eliminar apenas lo suficiente para mantener la cantidad de tokens de entrada por debajo del límite. La idea es descartar una parte mayor de la ventana de contexto de una sola vez, en lugar de descartar un poco en cada turno. Así se invalida la caché con menos frecuencia, lo que puede reducir los costos en sesiones largas que alcanzan el límite de entrada.

{
  "type": "session.update",
  "session": {
    "truncation": {
      "type": "retention_ratio",
      "retention_ratio": 0.8
    }
  }
}

Llamada asíncrona a funciones

La Responses API exige que la respuesta de una función llegue inmediatamente después de la llamada. La Realtime API, en cambio, permite que los clientes continúen la sesión mientras la llamada está pendiente. Esto mejora la experiencia del usuario porque la conversación puede seguir su curso en tiempo real, aunque a veces el modelo inventa el contenido de una respuesta que la función aún no ha dado.

Para mitigar este problema, la versión GA de la Responses API incorpora respuestas provisionales. Evaluamos y ajustamos su contenido en distintos experimentos para que el modelo responda de forma adecuada incluso mientras espera la respuesta de una función. Si le preguntas por el resultado de una llamada, dirá algo como “Todavía estoy esperando el resultado”. Esta función se activa automáticamente en los modelos nuevos, sin que tengas que hacer ningún cambio.

Residencia de datos en la UE

La residencia de datos en la UE ahora está disponible específicamente para los modelos gpt-realtime-2025-08-28 y gpt-4o-realtime-preview-2025-06-03. Para usarla, debes activarla explícitamente para la organización y acceder a la API a través de https://eu.api.openai.com.

Trazas

La Realtime API guarda trazas en la consola para desarrolladores. Estas trazas registran eventos importantes de las sesiones en tiempo real y pueden ayudarte a investigar y depurar problemas. Con la versión GA incorporamos nuevos tipos de eventos:

• Actualización de la sesión (cuando se envían eventos session.updated al cliente)
• Generación de texto de salida (para el texto generado por el modelo)

Prompts alojados

Ahora puedes usar prompts con la Realtime API para que el código de tu aplicación haga referencia a un prompt que puedes editar por separado. Los prompts incluyen tanto las instrucciones como la configuración de la sesión, por ejemplo, los ajustes de detección de turnos.

Puedes crear un prompt en el Playground de Realtime, ajustarlo y crear nuevas versiones según lo necesites. Luego, el cliente puede hacer referencia al prompt mediante su ID, como en este ejemplo:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "pmpt_123", // your stored prompt ID
      "version": "89", // optional: pin a specific version
      "variables": {
        "city": "Paris" // example variable used by your prompt
      }
    },
    // You can still set direct session fields; these override prompt fields if they overlap:
    "instructions": "Speak clearly and briefly. Confirm understanding before taking actions."
  }
}

Si un ajuste del prompt también se especifica en la configuración que se envía a la sesión, como en el ejemplo anterior, la configuración de la sesión tiene prioridad. Así, el cliente puede usar la configuración del prompt o modificarla durante la sesión.

Conexiones por un canal auxiliar

La Realtime API permite que los clientes se conecten directamente al servidor de la API mediante WebRTC o SIP. Sin embargo, probablemente te convenga gestionar el uso de herramientas y el resto de la lógica de negocio en el servidor de tu aplicación. Así mantienes esa lógica privada e independiente del cliente.

Para mantener el uso de herramientas, la lógica de negocio y otros detalles protegidos en el servidor, conéctate a través de un canal de control auxiliar. Ahora puedes usar un canal auxiliar tanto con conexiones SIP como con conexiones WebRTC.

Con un canal auxiliar hay dos conexiones activas a la misma sesión en tiempo real. Una proviene del cliente del usuario y la otra, del servidor de tu aplicación. Puedes usar la conexión del servidor para supervisar la sesión, actualizar las instrucciones y responder a las llamadas a herramientas.

Para obtener más información, consulta la documentación sobre las conexiones por un canal auxiliar.

Empieza a desarrollar

Esperamos que estas notas te hayan ayudado a entender los cambios que traen la versión de disponibilidad general de la Realtime API y los nuevos modelos en tiempo real.

Ahora que conoces los cambios, consulta la documentación de Realtime para crear un agente de voz, iniciar una conexión o empezar a enviar prompts a los modelos en tiempo real.