Exploración de Azure Voice Live API

Voice live API permite a los desarrolladores crear aplicaciones habilitadas para voz con comunicación bidireccional en tiempo real. En esta unidad se explora su arquitectura, configuración e implementación.

Características clave de Voice Live API

Voice live API proporciona comunicación en tiempo real mediante conexiones WebSocket. Admite características avanzadas como el reconocimiento de voz, la síntesis de texto a voz, el streaming de avatares y el procesamiento de audio.

• Los eventos con formato JSON administran conversaciones, secuencias de audio y respuestas.
• Los eventos se clasifican en eventos de cliente (enviados de cliente a servidor) y eventos de servidor (enviados desde el servidor al cliente).

Entre las características clave se incluyen:

• Procesamiento de audio en tiempo real compatible con varios formatos como PCM16 y G.711.
• Opciones avanzadas de voz, incluidas las voces de OpenAI y las voces personalizadas de Azure.
• Integración de Avatar con WebRTC para vídeo y animación.
• Reducción de ruido integrada y cancelación de eco.

Para obtener una tabla de modelos y regiones admitidos, visite la introducción a Voice Live API.

Conexión a Voice Live API

Voice Live API admite dos métodos de autenticación: Microsoft Entra (sin claves) y clave de API. Microsoft Entra usa la autenticación basada en tokens para un recurso de Microsoft Foundry. Se aplica un token de autenticación recuperado usando un token Bearer con el encabezado Authorization.

Para la autenticación sin clave recomendada con el identificador de Entra de Microsoft, debe asignar el rol de usuario de Cognitive Services a su cuenta de usuario o a una identidad administrada. Se genera 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>.

Para el acceso a claves, se puede proporcionar una clave de API de una de estas dos maneras. Puede usar un encabezado de conexión api-key en la conexión anterior al protocolo de enlace. Esta opción no está disponible en un entorno del explorador. O bien, puede usar un api-key parámetro de cadena de consulta en el URI de solicitud. Los parámetros de cadena de consulta se cifran al usar https/wss.

Punto de conexión de WebSocket

El punto de conexión que se va a usar varía en función de cómo quiera acceder a los recursos. Puede acceder a los recursos a través de una conexión al proyecto ai Foundry (Agente) o a través de una conexión al modelo.

• Conexión del proyecto: El punto de conexión es wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01
• Conexión de modelo: El punto de conexión es 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.

Eventos de Voice Live API

Los eventos de cliente y servidor facilitan la comunicación y el control dentro de voice live API. Entre los eventos de cliente clave se incluyen:

• session.update: modifique las configuraciones de sesión.
• input_audio_buffer.append: Agregue datos de audio al buffer.
• response.create: genere respuestas a través de la inferencia del modelo.

Los eventos de servidor proporcionan comentarios y actualizaciones de estado:

• session.updated: confirme los cambios de configuración de sesión.
• response.done: indica la finalización de la generación de respuestas.
• conversation.item.created: notificar cuándo se agrega un nuevo elemento de conversación.

Para obtener una lista completa de eventos de cliente o servidor, visite Referencia de api dinámica de voz.

Configuración de las opciones de sesión para Voice Live API

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. La configuración de sesión se puede actualizar dinámicamente mediante el session.update evento . Los desarrolladores pueden configurar tipos de voz, modalidades, detección de turnos y formatos de audio.

Configuración de ejemplo:

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Implementación del procesamiento de audio en tiempo real con voice live API

El procesamiento de audio en tiempo real es una característica principal de voice live API. Los desarrolladores pueden anexar, confirmar y borrar búferes de audio mediante eventos de cliente específicos.

• Anexar audio: Agregue bytes de audio al búfer de entrada.
• Confirmar audio: procese el búfer de audio para la generación de transcripción o de respuestas.
• Borrar audio: Elimine los datos de audio del búfer.

La reducción del ruido y la cancelación del eco se pueden configurar para mejorar la calidad del audio. Por ejemplo:

{
  "type": "session.update",
  "session": {
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "input_audio_echo_cancellation": {
      "type": "server_echo_cancellation"
    }
  }
}

Integración del streaming de avatares mediante voice live API

Voice Live API admite el streaming de avatares basado en WebRTC para aplicaciones interactivas. Los desarrolladores pueden configurar las opciones de vídeo, animación y blendshape.

• Utilice el session.avatar.connect evento para proporcionar la oferta de SDP del cliente.
• Configure la resolución de vídeo, la velocidad de bits y los valores del códec.
• Defina salidas de animación como blendshapes y visemes.

Configuración de ejemplo:

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}