Compartir vía

Cómo utilizar la Voice Live API

Voice Live API proporciona una interfaz WebSocket compatible en comparación con la API realtime de Azure OpenAI.

A menos que se indique lo contrario, la API de voz en vivo utiliza los mismos eventos que la API en tiempo real de Azure OpenAI. En este documento se proporciona una referencia para las propiedades del mensaje de evento específicas de Voice Live API.

Modelos y regiones admitidos

Para obtener una tabla de los modelos y regiones admitidos, consulte la introducción a la API dinámica de voz.

Authentication

Se requiere un recurso de Microsoft Foundry o un recurso de Azure Speech in Foundry Tools Services para usar voice live API.

Note

El uso de Voice Live API está optimizado para los recursos de Microsoft Foundry. Se recomienda usar recursos de Microsoft Foundry para obtener una disponibilidad completa de las características y la mejor experiencia de integración de Microsoft Foundry.
Los recursos de Azure Speech Services no admiten la integración de Microsoft Foundry Agent Service ni la opción de traer su propio modelo (BYOM).

Punto de conexión de WebSocket

El punto de conexión de WebSocket para voice live API es wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01 o, para recursos más antiguos, wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01. El punto de conexión es el mismo para todos los modelos. La única diferencia es el parámetro de consulta necesario model o, al usar el servicio agente, los parámetros agent_id y project_id.

Por ejemplo, un punto de conexión de un recurso con un dominio personalizado sería wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01&model=gpt-realtime

Credentials

Voice Live API admite dos métodos de autenticación:

  • Microsoft Entra (recomendado): use la autenticación basada en tokens para un recurso de Microsoft Foundry. Aplicar un token de autenticación recuperado utilizando un token Bearer con el encabezado Authorization.
  • Clave API: un api-key se puede proporcionar de dos maneras:
    • Utilizar un encabezado de conexión api-key en la conexión prehandshake. Esta opción no está disponible en un entorno del explorador.
    • Usar un parámetro de cadena de consulta api-key en el URI de solicitud. Los parámetros de cadena de consulta se cifran al usar https/wss.

Para la autenticación sin clave recomendada con Microsoft Entra ID, debe hacer lo siguiente:

  • Asigne los roles Cognitive Services User y Azure AI User a su cuenta de usuario o a una identidad administrada. Puede asignar roles en el portal de Azure bajo control de acceso (IAM)>Agregar asignación de roles.
  • Genere un token mediante la CLI de Azure o los SDK de Azure. El token debe generarse con el ámbito https://ai.azure.com/.default o el ámbito heredado https://cognitiveservices.azure.com/.default.
  • Use el token en el Authorization encabezado de la solicitud de conexión de WebSocket, con el formato Bearer <token>.

Configuración de sesión

A menudo, el primer evento enviado por el autor de la llamada en una sesión recién establecida de la API de voz en vivo es el evento session.update. Este evento controla un amplio conjunto de comportamientos de entrada y salida, con propiedades de generación de salida y respuesta que después se pueden invalidar usando el evento response.create.

Este es un mensaje de ejemplo session.update que configura varios aspectos de la sesión, incluida la detección de turnos, el procesamiento de audio de entrada y la salida de voz. La mayoría de los parámetros de sesión son opcionales y se pueden omitir si no es necesario.

{
    "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
    "turn_detection": {
        "type": "azure_semantic_vad",
        "threshold": 0.3,
        "prefix_padding_ms": 200,
        "silence_duration_ms": 200,
        "remove_filler_words": false,
        "end_of_utterance_detection": {
            "model": "semantic_detection_v1",
            "threshold_level": "default",
            "timeout_ms": 1000
        },
    },
    "input_audio_noise_reduction": {"type": "azure_deep_noise_suppression"},
    "input_audio_echo_cancellation": {"type": "server_echo_cancellation"},
    "voice": {
        "name": "en-US-Ava:DragonHDLatestNeural",
        "type": "azure-standard",
        "temperature": 0.8,
    },
}

Importante

La "instructions" propiedad no se admite cuando se usa un agente personalizado.

El servidor responde con un session.updated evento para confirmar la configuración de la sesión.

Propiedades de sesión

En las secciones siguientes se describen las propiedades del session objeto que se pueden configurar en el session.update mensaje.

Tip

Para obtener descripciones completas de los eventos y propiedades admitidos, consulte la Documentación de referencia de eventos de API en tiempo real de Azure OpenAI. En este documento se proporciona una referencia para las propiedades del mensaje de evento que son mejoradas mediante la Voice Live API.

Propiedades de audio de entrada

Puede usar las propiedades de audio de entrada para configurar la secuencia de audio de entrada.

Property Type Obligatorio u opcional Description
input_audio_sampling_rate integer Optional Frecuencia de muestreo del audio de entrada.

Los valores admitidos son 16000 y 24000. El valor predeterminado es 24000.
input_audio_echo_cancellation object Optional Mejora la calidad del audio de entrada quitando el eco de la propia voz del modelo sin necesidad de cancelación de eco del lado cliente.

Establezca latype propiedad de input_audio_echo_cancellation para habilitar la cancelación de eco.

El valor admitido para type es server_echo_cancellation, que se usa cuando la voz del modelo se reproduce de vuelta al usuario final a través de un altavoz, y el micrófono recoge la propia voz del modelo.
input_audio_noise_reduction object Optional Mejora la calidad del audio de entrada suprimiendo o eliminando el ruido de fondo ambiental.

Establezca la propiedad type de input_audio_noise_reduction para habilitar la supresión de ruido.

El valor admitido para type es azure_deep_noise_suppression, que optimiza los altavoces más cercanos al micrófono.

Puede establecer esta propiedad en near_field o far_field si usa la API Realtime de Azure OpenAI.

Este es un ejemplo de cómo las propiedades de audio de entrada son un objeto de sesión.

{
    "input_audio_sampling_rate": 24000,
    "input_audio_noise_reduction": {"type": "azure_deep_noise_suppression"},
    "input_audio_echo_cancellation": {"type": "server_echo_cancellation"},
}

Supresión de ruido y cancelación de eco

La supresión de ruido mejora la calidad de audio de entrada mediante la supresión o eliminación del ruido de fondo ambiental. La supresión de ruido ayuda al modelo a comprender al usuario final con mayor precisión y mejora la precisión de las señales de audio, como la detección de interrupciones y la detección de fin de turno.

La cancelación del eco del servidor mejora la calidad del audio de entrada quitando el eco de la propia voz del modelo. De este modo, no se requiere la cancelación de eco del lado del cliente. La cancelación de eco del servidor es útil cuando la voz del modelo se reproduce al usuario final a través de un altavoz. Esto ayuda a evitar que el micrófono recoja la propia voz del modelo.

Note

El servicio supone que el cliente reproduce audio de respuesta en cuanto los recibe. Si la reproducción se retrasa durante más de dos segundos, la calidad de la cancelación de eco se ve afectada.

Mejoras conversacionales

Voice live API ofrece mejoras conversacionales para proporcionar solidez al flujo natural de conversación del usuario final.

Parámetros de detección de turnos

La detección de turnos es el proceso de detectar cuando el usuario final comenzó o dejó de hablar. Voice Live API se basa en la propiedad API turn_detection realtime de Azure OpenAI para configurar la detección de turnos. Los tipos azure_semantic_vad y azure_multilingual_semantic_vad y los avanzados end_of_utterance_detection son diferenciadores clave entre la API en vivo de voz y la API en tiempo real de Azure OpenAI.

Property Type Obligatorio u opcional Description
type string Optional Tipo de sistema de detección de turnos que se va a usar. El tipo server_vad detecta el inicio y el final de la voz en función del volumen de audio.

El tipo semantic_vad usa un clasificador semántico para detectar cuándo el usuario ha terminado de hablar, en función de las palabras que han dicho. Este tipo solo se puede usar con los modelos gpt-realtime y gpt-realtime-mini .

El tipo azure_semantic_vad y azure_semantic_vad_multilingual también detecta el inicio y el final de la voz en función del significado semántico y se puede usar con todos los modelos. Además, la detección de actividad de voz semántica de Azure (VAD) también puede mejorar la detección de turnos mediante la eliminación de palabras de relleno para reducir la tasa de falsa alarma de entrada.

El valor predeterminado es server_vad.
threshold number Optional Un umbral superior requiere una señal de mayor confianza del usuario que intenta hablar.
prefix_padding_ms integer Optional Cantidad de audio, medida en milisegundos, que se incluirá antes del inicio de la señal de detección de voz.
speech_duration_ms integer Optional Duración del audio de voz del usuario necesario para iniciar la detección. Si no se establece o tiene menos de 80 ms, el detector usa un valor predeterminado de 80 ms.
silence_duration_ms integer Optional La duración del silencio del usuario, medida en milisegundos, para detectar el final de la voz.
remove_filler_words boolean Optional Determine si se van a quitar palabras de relleno para reducir la tasa de falsas alarmas de entrada.
Para habilitarla, la propiedad debe establecerse en true. Las palabras de relleno detectadas en inglés son ['ah', 'umm', 'mm', 'uh', 'huh', 'oh', 'yeah', 'hmm']. El servicio omite estas palabras cuando hay una respuesta en curso. La característica para quitar palabras de relleno supone que el cliente reproduce el audio de respuesta en cuanto lo recibe.
El valor predeterminado es false.
languages string[] Optional El idioma se usará para mejorar la remove_filler_words precisión al reducir el número de idiomas aplicados. El tipo azure_semantic_vad admite principalmente inglés. El tipo azure_semantic_vad_multilingual también está disponible para admitir una variedad más amplia de idiomas: inglés, español, francés, italiano, alemán (DE), japonés, portugués, chino, coreano, hindi. Se omitirán otros idiomas.
create_response boolean Optional Habilite o deshabilite si se genera una respuesta.
eagerness string Optional Esta es una manera de controlar cuán dispuesto está el modelo a interrumpir al usuario, ajustando el tiempo máximo de espera. Solo está disponible con el tipo semantic_vad. En el modo de transcripción, incluso si el modelo no responde, afecta a cómo se fragmenta el audio.
Se permiten los siguientes valores:
- auto (valor predeterminado) es equivalente a medium,
- low permitirá que el usuario se tome su tiempo para hablar,
- high fragmentará el audio lo antes posible.

Si desea que el modelo responda con más frecuencia en el modo de conversación o para devolver eventos de transcripción más rápido en el modo de transcripción, puede establecer el entusiasmo en high.
Por otro lado, si desea permitir que el usuario hable sin interrupciones en el modo de conversación, o si desea fragmentos de transcripción más grandes en el modo de transcripción, puede establecer el entusiasmo en low.
interrupt_response boolean Optional Habilite o deshabilite la interrupción de barge-in (valor predeterminado: falso). Solo está disponible con el tipo azure_semantic_vad y azure_semantic_vad_multilingual.
auto_truncate boolean Optional Truncar automáticamente al interrumpirse (valor predeterminado: false).
end_of_utterance_detection object Optional Configuración para la detección del final de la expresión. Voice live API ofrece una detección avanzada de fin de turno para indicar cuándo el usuario final dejó de hablar mientras permite pausas naturales. La detección de finales de expresiones puede reducir significativamente las señales prematuras de fin de turno sin agregar latencia que se pueda percibir por el usuario. Se puede usar la detección de final de expresiones con cualquiera de las selecciones de VAD.

Entre las propiedades de end_of_utterance_detection se incluyen:
- model: modelo que se va a usar para la detección del final de la expresión. Los valores admitidos son:
   semantic_detection_v1 compatible con inglés.
   semantic_detection_v1_multilingual admite inglés, español, francés, italiano, alemán (DE), japonés, portugués, chino, coreano, hindi.
Se omiten otros idiomas.
- threshold_level: configuración de la opción para el nivel de umbral de detección (low, medium, y highdefault), el valor predeterminado es igual a medium. Con un valor inferior, la probabilidad de que se complete la oración será mayor.
- timeout_ms: configuración opcional para el tiempo máximo en milisegundos para esperar más habla del usuario. Su valor predeterminado es 1 000 ms.

La detección de final de expresiones no admite actualmente gpt-realtime, gpt-4o-mini-realtime ni phi4-mm-realtime.

Este es un ejemplo de detección de fin de expresión en un objeto de sesión:

{
    "session": {
        "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
        "turn_detection": {
            "type": "azure_semantic_vad",
            "threshold": 0.3,
            "prefix_padding_ms": 300,
            "speech_duration_ms":80,
            "silence_duration_ms": 500,
            "remove_filler_words": false,
            "end_of_utterance_detection": {
                "model": "semantic_detection_v1",
                "threshold_level": "default",
                "timeout_ms": 1000
            }
        }
    }
}

Entrada de audio a través de la conversión de voz en texto de Azure

La conversión de voz en texto de Azure se activa automáticamente cuando se usa un modelo no bidireccional como gpt-4o.

Para configurarlo explícitamente, puede establecer el model a azure-speech en input_audio_transcription. Esto puede ser útil para mejorar la calidad del reconocimiento para situaciones de idioma específicas. Consulte Cómo personalizar la entrada y salida de voz en directo para obtener más información sobre la configuración de personalización de entrada de voz.

{
    "session": {
        "input_audio_transcription": {
            "model": "azure-speech",
            "language": "en"
        }
    }
}

Salida de audio a través de texto de Azure a voz

Puede usar el voice parámetro para especificar una voz estándar o personalizada. La voz se usa para la salida de audio.

El objeto voice tiene las siguientes propiedades:

Property Type Obligatorio u opcional Description
name string Required Especifica el nombre de la voz. Por ejemplo: en-US-AvaNeural.
type string Required Configuración del tipo de voz de Azure entre azure-standard y azure-custom.
temperature number Optional Especifica la temperatura aplicable a las voces de Azure HD. Los valores más altos proporcionan niveles más altos de variabilidad en la entonación, prosodia, etc.

Para obtener más información sobre la configuración de personalización de salida de voz, consulte Personalización de la entrada y salida en directo de voz.

Voces estándar de Azure

Este es un ejemplo de mensaje parcial para una voz estándar (azure-standard):

{
  "voice": {
    "name": "en-US-AvaNeural",
    "type": "azure-standard"
  }
}

Para obtener la lista completa de voces estándar, consulte Compatibilidad con idiomas y voz para el servicio de voz.

Voces de alta definición de Azure

Este es un mensaje de ejemplo session.update para una voz de alta definición estándar:

{
  "voice": {
    "name": "en-US-Ava:DragonHDLatestNeural",
    "type": "azure-standard",
    "temperature": 0.8 // optional
  }
}

Para obtener la lista completa de voces de alta definición estándar, consulte la documentación de voces de alta definición.

Note

Actualmente solo se admiten voces de alta definición en las siguientes regiones: southeastasia, centralindia, swedencentral, westeurope, eastus, eastus2, westus2

Tasa de habla

Use la propiedad de cadena rate para ajustar la velocidad de habla de cualquier texto estándar de Azure a voces de voz y voces personalizadas.

El valor de velocidad debe oscilar entre 0,5 y 1,5, con valores más altos que indican velocidades más rápidas.

{
  "voice": {
    "name": "en-US-Ava:DragonHDLatestNeural",
    "type": "azure-standard",
    "temperature": 0.8, // optional
    "rate": "1.2"
  }
}

Marcas de tiempo de audio

Cuando se usan voces de Azure y output_audio_timestamp_types se configura, el servicio devuelve en response.audio_timestamp.delta la respuesta y response.audio_timestamp.done cuando se devuelven todas las marcas de tiempo.

Para configurar las marcas de tiempo de audio, puede establecer en output_audio_timestamp_types el mensaje session.update.

{
    "session": {
        "output_audio_timestamp_types": ["word"]
    }
}

El servicio devuelve las marcas de tiempo de audio en la respuesta cuando se genera el audio.

{
    "event_id": "<event_id>",
    "type": "response.audio_timestamp.delta",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
    "output_index": 0,
    "content_index": 0,
    "audio_offset_ms": 490,
    "audio_duration_ms": 387,
    "text": "end",
    "timestamp_type": "word"
}

Y se envía un response.audio_timestamp.done mensaje cuando se devuelven todas las marcas de tiempo.

{
    "event_id": "<event_id>",
    "type": "response.audio_timestamp.done",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
}

Viseme

Un visema es la descripción visual de un fonema en lenguaje hablado. Define la posición de la cara y la boca cuando una persona habla.

Puede usar la voz estándar de Azure o la voz personalizada de Azure con animation.outputs establecido en {"viseme_id"}. El servicio devuelve el response.animation_viseme.delta en la respuesta y el response.animation_viseme.done cuando se han devuelto todos los mensajes de visema.

Tip

Para obtener más información sobre el viseme a través del lenguaje de marcado de síntesis de voz (SSML), consulte la documentación del elemento viseme.

Para configurar el visema, puede establecer animation.outputsen el session.update mensaje. El animation.outputs parámetro es opcional. Configura qué salidas de animación se deben devolver. Actualmente, solo admite viseme_id.

{
  "type": "session.update",
  "event_id": "your-session-id",
  "session": {
    "voice": {
      "name": "en-US-AvaNeural",
      "type": "azure-standard",
    },
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
    "turn_detection": {
        "type": "server_vad"
    },
    "output_audio_timestamp_types": ["word"], // optional
    "animation": {
        "outputs": ["viseme_id"], // optional
    },
  }
}

El output_audio_timestamp_types parámetro es opcional. Configura las marcas de tiempo de audio que se deben devolver para el audio generado. Actualmente, solo admite word.

El servicio devuelve la alineación del visema en la respuesta cuando se genera el audio.

{
    "event_id": "<event_id>",
    "type": "response.animation_viseme.delta",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
    "output_index": 0,
    "content_index": 0,
    "audio_offset_ms": 455,
    "viseme_id": 20
}

Y se envía un mensaje response.animation_viseme.done cuando se devuelven todos los mensajes del visema.

{
    "event_id": "<event_id>",
    "type": "response.animation_viseme.done",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
}

Avatar de texto a voz de Azure

El avatar de texto a voz convierte el texto en un vídeo digital de un ser humano fotorealista (ya sea un avatar estándar o un avatar de texto a voz personalizado) hablando con una voz de sonido natural.

Puede usar el avatar parámetro para especificar un avatar estándar o personalizado. El avatar se sincroniza con la salida de audio.

Se puede especificar un avatar parámetro para habilitar la salida del avatar que se sincroniza con la salida de audio:

{
  "session": {
    "avatar": {
      "character": "lisa",
      "style": "casual-sitting",
      "customized": false,
      "ice_servers": [
        {
          "urls": ["REDACTED"],
          "username": "",
          "credential": ""
        }
      ],
      "video": {
        "bitrate": 2000000,
        "codec": "h264",
        "crop": {
          "top_left": [560, 0],
          "bottom_right": [1360, 1080],
        },
        "resolution": {
          "width": 1080,
          "height": 1920,
        },
        "background": {
          "color": "#00FF00FF"
          // "image_url": "https://example.com/example.jpg"
        }
      }
    }
  }
}

El campo ice_servers es opcional. Si no lo especifica, el servicio devuelve los servidores ICE específicos del servidor en session.updated respuesta. Y debe usar los servidores ICE específicos del servidor para generar los candidatos de ICE locales.

Envíe el SDP de cliente después de que se recopilen los candidatos de ICE.

{
    "type": "session.avatar.connect",
    "client_sdp": "your-client-sdp"
}

Y el servicio responde con el SDP del servidor.

{
    "type": "session.avatar.connecting",
    "server_sdp": "your-server-sdp"
}

A continuación, puede conectar el avatar con el SDP del servidor.

Note

El avatar de texto a voz de Azure se admite actualmente en regiones limitadas. Para obtener la lista actual de regiones admitidas, consulte la tabla Regiones de servicio de voz.

Contenido relacionado

  • Last updated on