Alibaba Cloud Model Studio:Qwen-Audio Realtime WebSocket API reference

L'API Qwen-Audio Realtime permet des conversations vocales en temps réel via le protocole WebSocket. Les clients interagissent avec le serveur par l'envoi et la réception d'événements JSON. Cette API prend en charge les entrées audio et texte, la détection d'activité vocale (VAD), ainsi que la sortie en streaming audio et texte.

Guide utilisateur : Conversation audio en temps réel (Qwen-Audio-Realtime). Pour une description détaillée des événements client et serveur, consultez les rubriques Événements client et Événements serveur.

Endpoint du service

L'URL WebSocket est fixe. Spécifiez le nom du modèle à l'aide du paramètre de requête model (remplacez <model_name> par le nom réel du modèle) :

China (Beijing)

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

Remplacez {WorkspaceId} (y compris les accolades) par votre ID d'espace de travail réel.

En-têtes de requête

Incluez les en-têtes suivants dans votre requête :

Paramètre	Type	Obligatoire	Description
Authorization	string	Oui	Jeton d'authentification au format Bearer <your_api_key>. Remplacez <your_api_key> par votre clé API réelle.
user-agent	string	Non	Identifiant client pour le suivi des requêtes côté serveur.
X-DashScope-WorkSpace	string	Non	ID de l'espace de travail Alibaba Cloud Model Studio.

Concepts clés

• Session : Une connexion WebSocket unique correspond à une session qui conserve la configuration et le contexte de conversation.
• Élément de conversation : Message individuel au sein d'une conversation, maintenu dans un ordre séquentiel.
• Réponse : Sortie générée par une inférence unique du modèle, contenant un ou plusieurs éléments de sortie. Un élément de sortie peut être un message de l'assistant ou un appel de fonction.
• Appel de fonction : Élément généré par le modèle lorsqu'il nécessite l'exécution d'une fonction outil par le client. Après avoir exécuté l'outil, le client renvoie le résultat via function_call_output et déclenche l'inférence suivante avec response.create.
• Détection de tour de parole : Contrôle le moment où déclencher l'inférence du modèle.

Modes d'interaction

L'API Qwen-Audio Realtime prend en charge trois modes d'interaction, configurables via le paramètre turn_detection.type de l'événement session.update :

Mode	turn_detection.type	Description	Cas d'utilisation
server_vad	server_vad	La VAD côté serveur détecte le début et la fin de la parole, puis déclenche automatiquement l'inférence.	Conversation mains libres, assistants vocaux
smart_turn	smart_turn	Détection intelligente des tours de parole combinant analyse acoustique et sémantique pour déterminer les limites de prise de parole, au-delà des simples signaux vocaux. Les sons non sémantiques (comme « euh » ou « ah ») ne déclenchent pas de tour de parole ni n'interrompent la lecture.	Conversation naturelle à faible latence, interruption de haute qualité
push-to-talk	null	Le client soumet manuellement l'audio et déclenche l'inférence.	Push-to-talk, contrôle précis

Flux d'interaction

Pour une description détaillée des événements client et serveur, consultez les rubriques Événements client et Événements serveur.

Mode server_vad

Le serveur effectue une détection d'activité vocale sur le flux audio entrant et déclenche automatiquement l'inférence après avoir détecté la fin de la parole.

Activation : Définissez le paramètre turn_detection.type de l'événement session.update sur server_vad.

Tour de conversation complet

Le diagramme suivant illustre la séquence d'interaction typique en mode server_vad :

L'interaction se déroule comme suit :

1. Le client établit une connexion WebSocket et le serveur renvoie un événement session.created.
2. Le client envoie session.update pour configurer les paramètres de session, et le serveur répond par session.updated.
3. Le client envoie en continu input_audio_buffer.append pour diffuser les données audio.
4. Le serveur détecte le début de la parole et renvoie input_audio_buffer.speech_started. Il diffuse également les deltas de transcription ASR via conversation.item.input_audio_transcription.delta.
5. Le serveur détecte la fin de la parole et renvoie input_audio_buffer.speech_stopped, input_audio_buffer.committed et conversation.item.created.
6. Le serveur génère automatiquement une réponse en diffusant les deltas de texte et d'audio (response.audio_transcript.delta, response.audio.delta), puis renvoie finalement response.done.

Interruption utilisateur

Si la VAD détecte que l'utilisateur commence à parler pendant la lecture d'une réponse par le modèle, le serveur annule la réponse en cours (renvoie response.done avec le statut cancelled), puis entame un nouveau cycle d'entrée vocale et de réponse. Le diagramme suivant illustre la séquence d'interaction lors d'une interruption utilisateur :

Mode smart_turn

Le mode smart_turn détecte la fin de la parole en combinant perception acoustique et compréhension sémantique, filtrant ainsi les réponses de type backchannel, le bruit ambiant et autres sons non sémantiques. Ces sons non sémantiques sont transmis sous forme d'événements conversation.item.ambient_audio_transcription.delta sans déclencher de tour de conversation.

Activation : Définissez le paramètre turn_detection.type de l'événement session.update sur smart_turn.

Tour de conversation complet

Le diagramme suivant illustre la séquence d'interaction typique en mode smart_turn :

Différences principales par rapport au mode server_vad :

• Les sons non sémantiques (« euh », « ah », etc.) ne déclenchent pas d'inférence. Ils sont en revanche renvoyés via des événements ambient_audio_transcription.
• Une parole précédemment validée peut être invalidée (input_audio_buffer.speech_stopped renvoie reason=turn_invalid), auquel cas aucune inférence n'est déclenchée.
• En attendant la prochaine entrée de l'utilisateur, le client peut explicitement envoyer response.create pour déclencher une inférence.

Interruption utilisateur

La gestion des interruptions est globalement identique à celle du mode server_vad. Le diagramme suivant illustre la séquence d'interaction lors d'une interruption utilisateur :

Tour de parole invalide

Une parole précédemment validée peut être invalidée (input_audio_buffer.speech_stopped renvoie reason=turn_invalid), auquel cas aucune inférence n'est déclenchée. Le client doit continuer à envoyer l'audio et attendre la prochaine parole valide. Le diagramme suivant illustre la séquence d'interaction pour un tour de parole invalide :

Flux de configuration de l'amélioration du locuteur

En mode smart_turn, lorsque voiceprint_audio_urls est inclus dans le premier événement session.update, le serveur effectue de manière asynchrone l'enregistrement de l'empreinte vocale (chargement des caractéristiques audio du locuteur cible) et notifie au client la progression de cet enregistrement via des événements. Un échec de l'enregistrement de l'empreinte vocale ne bloque pas le déroulement normal de la conversation.

La séquence d'interaction pour l'enregistrement de l'empreinte vocale est la suivante :

1. Le client envoie session.update avec les URL audio de l'empreinte vocale dans turn_detection.voiceprint_audio_urls. Le serveur renvoie session.created.

2. Le serveur lance immédiatement l'enregistrement de l'empreinte vocale de façon asynchrone et pousse voiceprint_audio_list.in_progress avant de renvoyer session.updated. Cet événement contient l'item_id qui identifie de manière unique la tâche d'enregistrement.

3. Le serveur renvoie session.updated pour confirmer que la configuration de la session a pris effet.

4. Une fois l'enregistrement terminé, le serveur pousse un événement terminal (l'item_id correspond à celui de l'étape 2) :

   • Succès de l'enregistrement : voiceprint_audio_list.completed.
   • Échec de l'enregistrement : voiceprint_audio_list.failed, avec un champ reason décrivant la cause de l'échec (par exemple, impossibilité de télécharger l'URL audio).

Mode push-to-talk

Le client contrôle manuellement la soumission de l'audio et le déclenchement de l'inférence. Privilégiez ce mode pour contrôler précisément le moment où l'audio est soumis et où l'inférence débute.

Activation : Définissez le paramètre turn_detection de l'événement session.update sur null.

Tour de conversation complet

Le diagramme suivant illustre la séquence d'interaction typique en mode push-to-talk :

L'interaction se déroule comme suit :

1. Le client envoie en continu input_audio_buffer.append pour diffuser les données audio.
2. Une fois que l'utilisateur a fini de parler, le client envoie input_audio_buffer.commit pour valider le tampon.
3. Le client envoie response.create pour déclencher manuellement l'inférence.
4. Le serveur génère une réponse en diffusant le texte et l'audio.

Interruption utilisateur

Le client envoie response.cancel pour annuler la réponse en cours, et le serveur renvoie response.done (avec le statut cancelled et la raison client_cancelled). Le diagramme suivant illustre la séquence d'interaction lors d'une interruption utilisateur :

Contraintes opérationnelles des modes

Opération	push-to-talk	server_vad	smart_turn
session.update	Tous les paramètres peuvent être modifiés à l'état IDLE ; certains sont restreints hors état IDLE	Tous les paramètres peuvent être modifiés à l'état IDLE ; certains sont restreints hors état IDLE	Tous les paramètres peuvent être modifiés à l'état IDLE ; certains sont restreints hors état IDLE
input_audio_buffer.append	Autorisé	Autorisé	Autorisé
input_audio_buffer.commit	Autorisé	Ignoré	Ignoré
input_audio_buffer.clear	Autorisé	Ignoré	Ignoré
response.create	Autorisé. L'audio doit d'abord être validé via input_audio_buffer.commit. Non autorisé pendant la génération d'une réponse.	Autorisé lorsqu'aucune réponse n'est en cours de génération ; interdit pendant la génération d'une réponse	Autorisé en attendant la prochaine entrée de l'utilisateur ; interdit pendant un tour de parole actif (de input_audio_buffer.speech_started à response.done)
response.cancel	Autorisé (pendant l'inférence)	Autorisé (pendant l'inférence)	Autorisé (pendant l'inférence)
conversation.item.create/delete/retrieve	Autorisé	Autorisé	Autorisé

Gestion des erreurs

Type	Comportement	Exemples
Erreur client (invalid_request_error)	La connexion reste ouverte ; le client reçoit un événement d'erreur	Paramètres invalides, état non autorisé, item_id dupliqué
Erreur serveur (server_error)	Connexion interrompue	Échec de connexion LLM, défaillance du stockage