Migración de la versión preliminar a la versión de disponibilidad general de la API en tiempo real

La API de OpenAI GPT en tiempo real de Azure ahora está generalmente disponible (GA). Esta guía de migración le ayuda a actualizar las aplicaciones existentes para usar el protocolo ga. La versión de disponibilidad general presenta cambios en el uso del SDK, las direcciones URL del punto de conexión, los nombres de eventos y la configuración de sesión.

Qué cambia: paquetes de SDK, formato de dirección URL de punto de conexión, nombres de eventos y estructura de configuración de sesión.

Lo que no cambia: funcionalidad básica, compatibilidad con formato de audio y funcionalidades del modelo.

Tiempo de migración: la mayoría de las migraciones tardan entre 30 y 60 minutos.

Importante

La versión preliminar de la API está en desuso a partir del 30 de abril de 2026. Migre a la versión de disponibilidad general antes de esta fecha para evitar interrupciones del servicio.

Nota

Si va a compilar una nueva aplicación, consulte el inicio rápido de la API en tiempo real en su lugar. Esta guía solo sirve para migrar aplicaciones de versión preliminar existentes a disponibilidad general.

Requisitos previos

Antes de comenzar la migración, compruebe que tiene:

  • Un recurso existente de Azure OpenAI con una implementación de API Realtime que usa el protocolo Preview (Beta)
  • Acceso al portal de Azure con permisos para administrar recursos de Azure OpenAI
  • Capacidad de actualizar las dependencias del SDK en el entorno de desarrollo
  • Un entorno de prueba en el que puede validar los cambios antes de realizar la implementación en producción
  • Descripción de la implementación actual (WebSocket o WebRTC)

Compatibilidad con SDK

Para el protocolo de API GA en tiempo real, debe usar un SDK compatible y la versión correcta de la API.

Precaución

El protocolo de API de disponibilidad general en tiempo real y el formato de mensaje solo se admiten en los SDKs proporcionados por OpenAI. Los SDK de versión preliminar en tiempo real publicados anteriormente por Microsoft no admiten el protocolo de API de disponibilidad general.

Lista de SDK:

Importante

Debe usar OpenAI .NET v.2.9.0 o posterior. El protocolo de API de Google Analytics en tiempo real no se admite en versiones anteriores.

Versión de API / URL base.

Utiliza el formato de URL del punto de conexión de disponibilidad general en tus aplicaciones. Esta dirección URL debe contener /openai/v1 y no debe contener ninguna versión de API como 2025-04-01-preview.

Ejemplo de formato de punto de conexión de disponibilidad general:

https://<your-resource>.openai.azure.com/openai/v1/

Consulte información detallada sobre el formato del punto de conexión en este artículo. Vea un ejemplo de uso de formato de punto de conexión de GA en Inicio rápido en la API de GPT Realtime API para voz y audio.

Actualización de puntos de conexión de WebRTC

Si usa WebRTC para audio en tiempo real basado en explorador, debe actualizar dos puntos de conexión a las versiones de disponibilidad general.

Ahora se crean claves efímeras para solicitudes WebRTC con una solicitud POST /openai/v1/realtime/client_secrets en el punto de conexión de OpenAI de Azure (consulte los detalles de Guía paso a paso).

La dirección URL para inicializar la conexión WebRTC en el explorador es ahora /openai/v1/realtime/calls (consulte los detalles de la guía paso a paso).

Cambios de protocolo para clientes personalizados

Si implementa el protocolo de API en tiempo real en su propio cliente en lugar de usar los SDK oficiales, revise estos cambios detallados del protocolo.

OpenAI-Beta encabezado

No incluya el OpenAI-Beta: encabezado en ninguna de las solicitudes.

Eventos modificados

Las sesiones de conversión de voz a voz y transcripción en tiempo real ahora usan el mismo session.update evento. Este evento tiene un nuevo type campo con los siguientes valores posibles:

  • realtime para conversión de voz a voz
  • transcription para la transcripción de audio en tiempo real

Consulte el siguiente ejemplo de fragmento de código:

ws.on("open", function open() {
    ws.send(
        JSON.stringify({
            type: "session.update",
            session: {
                type: "realtime",
                model: "gpt-realtime",
                // ... additional configuration

El evento session.update cambió de formato, y algunas propiedades ahora están en diferentes ubicaciones. Consulte la referencia de API para obtener más información.

Se cambiaron los siguientes nombres de evento:

  • De response.text.delta a response.output_text.delta
  • De response.audio.delta a response.output_audio.delta
  • De response.audio_transcript.delta a response.output_audio_transcript.delta

Ahora todos los eventos de elemento de conversación tienen el campo object=realtime.item.

Se puede agregar un campo de estado al elemento de salida de la llamada de función. Este campo no tiene ningún efecto en la conversación.

Los tipos del contenido del mensaje para las respuestas del asistente cambiaron de la siguiente manera:

  • De type=text a type=output_text
  • De type=audio a type=output_audio

Nuevos eventos

Los eventos conversation.item.added y conversation.item.done se agregaron para controlar mejor las operaciones de larga duración, como el listado de herramientas MCP.

Solución de problemas

En esta sección se tratan los problemas comunes detectados durante la migración y sus soluciones.

La conexión de WebSocket devuelve 401 No autorizado

Síntoma: La conexión falla con un error de autenticación tras la actualización al endpoint de disponibilidad general.

Causa: el api-version parámetro de consulta ya no se admite en las direcciones URL del punto de conexión de GA.

Solución: Elimine api-version de la dirección URL del punto de conexión. Cambiar de:

wss://<resource>.openai.azure.com/openai/realtime?api-version=2025-04-01-preview

Para:

wss://<resource>.openai.azure.com/openai/v1/realtime

Controladores de eventos no se activan

Síntoma: las respuestas de audio o texto no se procesan después de la migración.

Causa: Los nombres de evento cambiaron entre versiones preliminares y de disponibilidad general.

Solución: actualice los nombres del controlador de eventos según los nuevos nombres de evento. Asegúrese de actualizar todas las ocurrencias, incluidos los controladores de errores.

Configuración de sesión rechazada

Síntoma: el servidor devuelve un error al enviar el session.update evento.

Causa: falta el campo obligatorio type en la configuración de sesión.

Solución: agregue el type campo a la configuración de sesión con el valor "realtime" de voz a voz o "transcription" para la transcripción de audio.

No se puede establecer la conexión WebRTC

Síntoma: la conexión WebRTC basada en explorador no se establece después de la migración.

Causa: Los puntos de conexión de WebRTC cambiaron en la versión de disponibilidad general.

Solución: actualice tanto el punto de conexión de la clave efímera como la dirección URL de conexión.

error de compatibilidad del SDK de .NET

Symptom: .NET aplicación produce errores al intentar usar el protocolo GA.

Cause: el protocolo ga requiere openAI .NET SDK versión 2.9.0 o posterior.

Solution: actualice el paquete del SDK de .NET a la versión 2.9.0 o posterior mediante:

dotnet add package OpenAI --version 2.9.0

Lista de comprobación

Use esta lista de comprobación para comprobar que la migración se ha completado:

  • SDK actualizado a la versión compatible con GA (Python ≥1.54.0, JavaScript ≥4.77.0, .NET ≥2.9.0)
  • Direcciones URL del endpoint cambiadas al formato /openai/v1/realtime
  • api-version parámetro de consulta quitado de las direcciones URL del punto de conexión
  • Nombres de evento actualizados (response.text.delta → response.output_text.delta, etc.)
  • type campo agregado a la session.update configuración de eventos
  • OpenAI-Beta encabezado quitado de implementaciones de cliente personalizadas
  • Puntos de conexión de WebRTC actualizados (si procede)
  • Aplicación probada correctamente en un entorno que no es de producción
  • Entrada de audio y salida comprobadas para que funcionen correctamente
  • No hay advertencias de desaprobación en los registros de la aplicación
  • Las métricas de rendimiento cumplen o superan las expectativas de línea base

Pasos siguientes

Al migrar a la versión de disponibilidad general de la API en tiempo real, explore estos recursos para mejorar la implementación:

  • Last updated on