Explorer l’API Azure Voice Live

L’API Voice live permet aux développeurs de créer des applications compatibles vocales avec communication bidirectionnelle en temps réel. Cette unité explore son architecture, sa configuration et son implémentation.

Fonctionnalités clés de l’API Voice Live

L’API Voice live fournit une communication en temps réel à l’aide de connexions WebSocket. Il prend en charge des fonctionnalités avancées telles que la reconnaissance vocale, la synthèse vocale, la diffusion en continu d’avatars et le traitement audio.

• Les événements au format JSON gèrent les conversations, les flux audio et les réponses.
• Les événements sont classés en événements clients (envoyés du client au serveur) et des événements serveur (envoyés du serveur au client).

Les principales fonctionnalités sont les suivantes :

• Traitement audio en temps réel avec prise en charge de plusieurs formats comme PCM16 et G.711.
• Options vocales avancées, notamment les voix OpenAI et les voix personnalisées Azure.
• Intégration d’avatar à l’aide de WebRTC pour la vidéo et l’animation.
• Réduction du bruit intégrée et annulation de l’écho.

Pour obtenir une table des modèles et régions pris en charge, consultez la vue d’ensemble de l’API Voice Live.

Se connecter à l’API Voice Live

L’API voice live prend en charge deux méthodes d’authentification : Microsoft Entra (sans clé) et clé API. Microsoft Entra utilise l’authentification basée sur des jetons pour une ressource Microsoft Foundry. Vous appliquez un jeton d’authentification récupéré en utilisant un jeton Bearer avec l’en-tête Authorization.

Pour l’authentification sans clé recommandée avec l’ID Microsoft Entra, vous devez affecter le rôle d’utilisateur Cognitive Services à votre compte d’utilisateur ou à une identité managée. Vous générez un jeton à l’aide des kits de développement logiciel (SDK) Azure CLI ou Azure. Le jeton doit être généré avec l’étendue https://ai.azure.com/.default ou l’étendue héritée https://cognitiveservices.azure.com/.default. Utilisez le jeton dans l’en-tête Authorization de la demande de connexion WebSocket, avec le format Bearer <token>.

Pour l’accès à la clé, une clé API peut être fournie de deux façons. Vous pouvez utiliser un en-tête de connexion api-key sur la connexion de pré-établissement de liaison. Cette option n’est pas disponible dans un environnement de navigateur. Vous pouvez également utiliser un api-key paramètre de chaîne de requête sur l’URI de requête. Les paramètres de chaîne de requête sont chiffrés lors de l’utilisation de https/wss.

Point de terminaison WebSocket

Le point de terminaison à utiliser varie selon la façon dont vous souhaitez accéder à vos ressources. Vous pouvez accéder aux ressources via une connexion au projet AI Foundry (Agent) ou via une connexion au modèle.

• Connexion du projet : Le point de terminaison est wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01
• Connexion de modèle : Le point de terminaison est wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01.

Le point de terminaison est le même pour tous les modèles. La seule différence est le paramètre de requête requis model ou, lors de l’utilisation du service Agent, des paramètres et agent_id des project_id paramètres.

Événements de l’API Voice Live

Les événements client et serveur facilitent la communication et le contrôle dans l’API voice live. Les événements clés du client sont les suivants :

• session.update: modifiez les configurations de session.
• input_audio_buffer.append: ajoutez des données audio à la mémoire tampon.
• response.create: Générer des réponses via l’inférence du modèle.

Les événements serveur fournissent des commentaires et des mises à jour d’état :

• session.updated: Confirmez les modifications de configuration de session.
• response.done: indiquez l’achèvement de la génération de réponse.
• conversation.item.created: notifier lorsqu’un nouvel élément de conversation est ajouté.

Pour obtenir la liste complète des événements client/serveur, consultez la référence de l’API live Voice.

Configurer les paramètres de session pour l’API Voice live

Souvent, le premier événement envoyé par l’appelant sur une session d’API voice live nouvellement établie est l’événement session.update . Cet événement contrôle un large ensemble de comportements d’entrée et de sortie. Les paramètres de session peuvent être mis à jour dynamiquement à l’aide de l’événement session.update . Les développeurs peuvent configurer des types vocaux, des modalités, une détection de tour et des formats audio.

Exemple de configuration :

{
  "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"
  }
}

Implémenter le traitement audio en temps réel avec l’API Voice live

Le traitement audio en temps réel est une fonctionnalité essentielle de l’API voice live. Les développeurs peuvent ajouter, valider et effacer des mémoires tampons audio à l’aide d’événements clients spécifiques.

• Ajouter l’audio : Ajoutez des octets audio à la mémoire tampon d’entrée.
• Valider un audio : traitez la mémoire tampon audio pour la transcription ou la génération d’une réponse.
• Effacer l’audio : Supprimez les données audio de la mémoire tampon.

La réduction du bruit et l’annulation de l’écho peuvent être configurées pour améliorer la qualité audio. Par exemple:

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

Intégrer le streaming d’avatars à l’aide de l’API Voice live

L’API voice live prend en charge le streaming d’avatars webRTC pour les applications interactives. Les développeurs peuvent configurer des paramètres vidéo, d’animation et blendshape.

• Utilisez l’événement session.avatar.connect pour fournir l’offre SDP du client.
• Configurez les paramètres de résolution vidéo, de vitesse de transmission et de codec.
• Définissez des sorties d’animation telles que blendshapes et visemes.

Exemple de configuration :

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