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 disponibilidad general (GA) con mejoras importantes en la calidad del modelo, la confiabilidad y la facilidad de uso para desarrolladores.

Aunque puedes conocer las nuevas funciones de la API en la documentación y la referencia de la API, queremos destacar algunas que quizá pasaste por alto y orientarte sobre cuándo usarlas. Si estás desarrollando una integración con la Realtime API, esperamos que estas notas te resulten interesantes.

Mejoras del modelo

El nuevo modelo incluye varias mejoras para responder mejor a las necesidades de las aplicaciones de voz en producción. En esta publicación nos centramos en los cambios de la API. Para comprender y usar mejor el modelo, te recomendamos la publicación del anuncio en el blog y la guía de diseño de prompts para tiempo real. De todos modos, aquí señalaremos algunos detalles.

Algunos consejos clave para usar este modelo:

• Experimenta con el diseño de prompts en el Playground de tiempo real.
• Usa las voces marin o cedar para obtener la mejor calidad de voz del asistente.
• Reescribe los prompts para el nuevo modelo. Gracias a las mejoras en el seguimiento de instrucciones, las instrucciones específicas ahora tienen mucho más efecto.
  • Por ejemplo, el modelo anterior podía interpretar un prompt que dijera “Di siempre X cuando ocurra Y” como una orientación vaga, mientras que el nuevo modelo puede seguirlo en situaciones inesperadas.
  • Presta atención a las instrucciones específicas que proporcionas. Da por hecho que se seguirán.

Cambios en la estructura de la API

Actualizamos la estructura de la Realtime API con el lanzamiento de la versión GA, por lo que hay una interfaz beta y una interfaz GA. Recomendamos migrar los clientes para que se integren con la interfaz GA, ya que ofrece nuevas funciones y, con el tiempo, la interfaz beta quedará obsoleta.

Puedes encontrar la lista completa de los cambios necesarios para la migración en la documentación de migración de beta a GA.

Puedes acceder al nuevo modelo gpt-realtime con la interfaz beta, pero es posible que algunas funciones no sean compatibles. Consulta los detalles a continuación.

Disponibilidad de funciones

La versión GA de la Realtime API incluye varias funciones nuevas. Algunas están habilitadas en modelos anteriores y otras no.

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

Cambios en la temperatura

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

Quizá te preguntes: “¿Por qué los usuarios no pueden fijar cualquier valor de temperatura y usarlo, por ejemplo, para que la respuesta sea más determinista?”. La respuesta es que la temperatura se comporta de forma diferente en esta arquitectura de modelo, y casi siempre conviene usar el valor recomendado de 0.8.

Por lo que hemos observado, no hay forma de hacer que estas respuestas de audio sean deterministas con temperaturas bajas, y las temperaturas más altas producen anomalías en el audio. Recomendamos experimentar con el diseño de prompts para controlar estos aspectos del comportamiento del modelo.

Nuevas funciones

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

Todas las funciones se explican en la documentación y la referencia de la API, pero aquí destacaremos qué tener en cuenta sobre las nuevas funciones al integrar y migrar.

Tiempos de espera por inactividad en la conversación

En algunas aplicaciones, sería inesperado que pasara mucho tiempo sin recibir una entrada del usuario. Piensa en una llamada telefónica: si no escucháramos a la persona del otro lado de la línea, le preguntaríamos si todo está bien. Tal vez el modelo no captó lo que dijo el usuario, o tal vez el usuario no está seguro de si el modelo sigue hablando. Agregamos una función que hace que el modelo diga automáticamente algo como: “¿Sigues ahí?”.

Para habilitar esta función, define idle_timeout_ms en la configuración de server_vad para la detección de turnos. El tiempo de espera se aplicará una vez que termine de reproducirse el audio de la última respuesta del modelo; es decir, el vencimiento se fija en el momento de response.done más la duración de la reproducción del audio más el tiempo de espera. Si VAD no se activa durante ese período, se alcanza el tiempo de espera.

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

Los clientes pueden habilitar esta función de la siguiente 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 maneja las sesiones largas. Estos son algunos puntos que conviene tener en cuenta:

• Las sesiones en tiempo real ahora pueden durar hasta 60 minutos, frente a los 30 minutos anteriores.
• El modelo gpt-realtime tiene una ventana de 32 768 tokens. Las respuestas pueden consumir un máximo de 4096 tokens. Esto significa que el modelo admite una entrada máxima de 28 672 tokens.
• Las instrucciones de la sesión y las herramientas pueden tener una longitud máxima conjunta de 16 384 tokens.
• El servicio truncará (eliminará) mensajes automáticamente cuando la sesión alcance los 28 672 tokens, pero este comportamiento es configurable.
• El servicio de disponibilidad general eliminará automáticamente algunos tokens de audio cuando haya una transcripción disponible para ahorrar tokens.

Configurar el truncamiento

Cuando la ventana de contexto de la conversación alcanza el límite de tokens, la Realtime API comienza a truncar (eliminar) automáticamente los mensajes del inicio de la sesión (los más antiguos). Puedes desactivar este comportamiento de truncamiento con "truncation": "disabled"; en ese caso, se genera un error cuando una respuesta tiene demasiados tokens de entrada. Sin embargo, el truncamiento es útil porque permite que la sesión continúe aunque el tamaño de la entrada sea demasiado grande para el modelo. La Realtime API no resume ni compacta los mensajes eliminados, pero puedes implementar esta función por tu cuenta.

Un efecto negativo del truncamiento es que modificar los mensajes al inicio de la conversación invalida la caché de tokens del prompt. El almacenamiento de prompts en caché funciona identificando contenido que coincide exactamente al inicio de tus prompts. En cada turno posterior, solo se almacenan en caché los tokens que no han cambiado. Cuando el truncamiento altera el inicio de la conversación, reduce la cantidad de tokens que se pueden almacenar en caché.

Implementamos una función para mitigar este efecto negativo que elimina más contenido del necesario cada vez que se produce un truncamiento. Configura la proporción de retención en 0.8 para truncar el 20 % de la ventana de contexto, en lugar de truncar solo lo necesario para mantener la cantidad de tokens de entrada por debajo del límite. La idea es truncar más contenido de la ventana de contexto de una sola vez, en lugar de truncar un poco cada vez, para invalidar la caché con menos frecuencia. Este enfoque favorece el uso de la caché y puede mantener bajos los costos de las sesiones largas que alcanzan los límites de entrada.

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

Llamada asíncrona a funciones

Mientras que la API Responses exige una respuesta de la función inmediatamente después de la llamada a la función, la Realtime API permite que los clientes continúen una sesión mientras una llamada a una función está pendiente. Esto mejora la experiencia de usuario al permitir que las conversaciones en tiempo real continúen de forma natural, pero a veces el modelo inventa el contenido de una respuesta de función que no existe.

Para mitigar este problema, la versión de disponibilidad general de la API Responses agrega respuestas provisionales con contenido que evaluamos y ajustamos mediante experimentos para garantizar que el modelo se comporte de manera adecuada, incluso mientras espera la respuesta de una función. Si le preguntas al modelo por los resultados de una llamada a una función, dirá algo como “Todavía estoy esperando esos resultados”. Esta función se habilita automáticamente para los modelos nuevos; no necesitas hacer ningún cambio.

Residencia de datos en la UE

La residencia de datos en la UE ahora está disponible específicamente para gpt-realtime-2025-08-28 y gpt-4o-realtime-preview-2025-06-03. La residencia de datos debe habilitarse explícitamente para una organización y se debe acceder a ella a través de https://eu.api.openai.com.

Registro de trazas

La Realtime API guarda trazas en la consola para desarrolladores que registran eventos clave durante una sesión en tiempo real, lo que puede ser útil para investigar y depurar problemas. Como parte del lanzamiento de disponibilidad general, incorporamos algunos tipos de eventos nuevos:

• Sesión actualizada (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 de forma práctica a un prompt que se puede editar por separado. Los prompts incluyen tanto instrucciones como configuración de la sesión, por ejemplo, los ajustes de detección de turnos.

Puedes crear un prompt en el Playground en tiempo real, ajustarlo y crear versiones según lo necesites. Luego, un cliente puede hacer referencia a ese prompt mediante su ID, de esta manera:

{
  "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 se superpone con otra configuración enviada a la sesión, como en el ejemplo anterior, la configuración de la sesión tiene prioridad. Así, un cliente puede usar la configuración del prompt o modificarla durante la sesión.

Conexiones de canal lateral

La Realtime API permite que los clientes se conecten directamente al servidor de la API mediante WebRTC o SIP. Sin embargo, lo más probable es que prefieras mantener el uso de herramientas y el resto de la lógica de negocio en el servidor de tu aplicación para que esa lógica sea privada e independiente del cliente.

Mantén el uso de herramientas, la lógica de negocio y otros detalles seguros del lado del servidor conectándote a través de un canal lateral de control. Ahora ofrecemos opciones de canal lateral tanto para conexiones SIP como WebRTC.

Una conexión de canal lateral implica que hay dos conexiones activas a la misma sesión en tiempo real: una desde el cliente del usuario y otra desde el servidor de tu aplicación. La conexión del servidor se puede usar para monitorear la sesión, actualizar las instrucciones y responder a las llamadas a herramientas.

Para obtener más información, consulta la documentación sobre conexiones de canal lateral.

Empieza a desarrollar

Esperamos que esta explicación te haya ayudado a comprender los cambios de la versión de disponibilidad general de la Realtime API y los nuevos modelos en tiempo real.

Ahora que conoces las novedades, consulta la documentación sobre tiempo real para crear un agente de voz, iniciar una conexión o empezar a escribir prompts para modelos en tiempo real.