Connexion WebSocket à Qwen-Omni-Realtime
Périmètre d’application
Ce document concerne Qwen-Omni-Realtime. Le modèle de l’exemple est qwen3.8-omni-flash-realtime ; les configurations de qwen3.5-omni-plus-realtime et qwen3.5-omni-flash-realtime figurent dans la référence des événements. Pour les paramètres de l’ancien modèle qwen3-omni-flash-realtime-2025-09-15, consultez SDK Python.
- Utilisez l’API Key et l’ID de l’espace de travail correspondant à la région et à l’espace de travail sélectionnés.
- domaine de Singapour :
{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. - Les API Keys à longue durée de validité sont stockées sur le serveur et ne doivent pas être placées dans les navigateurs ou les applications mobiles.
Adresses et authentification
WebSocket
wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtimeqwen3.8-omni-flash-realtime doit utiliser le domaine propre à l’espace de travail. Les anciens modèles peuvent continuer à utiliser leurs domaines d’origine : Pékin utilise wss://dashscope.aliyuncs.com et Singapour utilise wss://dashscope-intl.aliyuncs.com. Pour plus d’informations, consultez SDK Python.
Définissez Authorization: Bearer <API_KEY> dans l’en-tête de la requête de négociation WebSocket. Remplacez l’ID de l’espace de travail et le nom réel du modèle ; ne placez pas les API Keys à longue durée de validité dans les navigateurs ou les applications mobiles.
L’en-tête facultatif user-agent identifie le client. La documentation générale d’intégration WebSocket présente également X-DashScope-WorkSpace (ID de l’espace de travail) et X-DashScope-DataInspection (configuration de vérification de conformité des données), à utiliser selon les exigences du modèle.
Pour générer des API Keys temporaires et connaître leurs autorisations, consultez Générer une API Key temporaire.
Les URL d’espace de travail suivantes utilisent qwen3.5-omni-plus-realtime comme modèle d’exemple.
- Chine (Pékin)
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime - Singapour
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
{WorkspaceId} par l’ID de l’espace de travail de la région sélectionnée.
Configuration de la session
Envoyez session.update après avoir établi la connexion et reçu session.created. N’envoyez les entrées qu’après la confirmation session.updated ; traitez les erreurs via les événements error.
Les exemples suivants correspondent à qwen3.8-omni-flash-realtime ; les autres versions doivent utiliser les configurations de leurs références d’événements respectives, sans mélanger les niveaux de champs.
Entrées, résultats et fin
L’audio est envoyé via input_audio_buffer.append ; les formats d’entrée, les conditions de soumission et les limites des entrées image sont décrits dans Événements client. Traitez les résultats, les états et les erreurs dans Événements serveur ; l’établissement de la connexion ne signifie pas que la requête métier est terminée.
Le déroulement des tours automatiques, du mode Manual, de Function Calling et de MCP est décrit dans Déroulement des interactions. Après avoir reçu les résultats nécessaires, fermez la connexion WebSocket.
Déroulement des interactions
Mode VAD
Pour activer le mode VAD, définissez le paramètre session.turn_detection.type de l’événement client sur "server_vad". Dans ce mode, le serveur effectue une détection d’activité vocale (VAD) sur l’audio entrant et répond lorsqu’il détecte la parole. Ce mode est le mode par défaut et convient aux scénarios où le client envoie continuellement l’audio au serveur.
- Le serveur émet l'événement
input_audio_buffer.speech_startedlorsqu'il détecte le début d'une parole. - Le client peut ajouter des données audio au tampon à tout moment en envoyant un événement
input_audio_buffer.append. - Le serveur signale la fin de la parole via l'événement
input_audio_buffer.speech_stopped. - Le serveur valide le tampon audio d'entrée en envoyant un événement
input_audio_buffer.committed. - Le serveur transmet ensuite un événement
conversation.item.createdcontenant l'élément de message utilisateur généré à partir du tampon audio.
Déroulement de Function Calling
En mode VAD, si une réponse générée par le serveur nécessite un appel d'outil, le flux d'interaction suivant se produit :
- Une fois la fin de la parole détectée et la réponse générée, le serveur détermine qu'un appel d'outil est nécessaire.
- Le serveur envoie un événement
response.function_call_arguments.deltacontenant les données incrémentielles des arguments de l'appel d'outil. - Le serveur transmet un événement
response.function_call_arguments.donepour indiquer que tous les arguments ont été envoyés. - Le client exécute l'appel d'outil et obtient le résultat.
- Le client envoie un événement
conversation.item.createcontenant le résultat de l'appel d'outil. - Le client envoie un événement
response.createpour déclencher une réponse fondée sur le résultat de l’appel d’outil.
Mode Manual
Pour activer le mode manuel, définissez le paramètre session.turn_detection de l'événement client sur null. Dans cette configuration, le client sollicite explicitement une réponse du serveur en envoyant les événements input_audio_buffer.commit et response.create. Ce mode convient particulièrement aux scénarios de type « push-to-talk », comme l'envoi de messages vocaux dans les applications de messagerie.
- Le client peut ajouter des données audio au tampon en envoyant un événement
input_audio_buffer.append. - Le client valide le tampon audio d'entrée en envoyant un événement
input_audio_buffer.commit. Cette validation crée un nouvel élément de message utilisateur dans la conversation. - Le serveur répond en envoyant un événement
input_audio_buffer.committed. - Le client envoie un événement
response.createpour déclencher la génération de la réponse finale par le modèle. - Le serveur répond en envoyant un événement
conversation.item.created.
Déroulement de Function Calling
- Après réception d'un événement
response.createprovenant du client, le serveur génère une réponse et identifie la nécessité d'un appel d'outil. - Le serveur envoie un événement
response.function_call_arguments.deltacontenant les données incrémentielles des arguments de l'appel d'outil. - Un événement
response.function_call_arguments.donesignale la fin du transfert des arguments. - Le client exécute l'appel d'outil et obtient le résultat.
- Le client transmet le résultat obtenu en utilisant un événement
conversation.item.create. - Le client envoie un événement
response.createpour déclencher la génération de la réponse finale par le modèle. - Le serveur produit une réponse fondée sur le résultat de l'outil et la transmet au client via des événements
response.audio.deltaouresponse.text.delta.
Appels d’outils MCP
Ce déroulement s’applique à Qwen3.8-Omni-Flash-Realtime avec le mode VAD ou Manual.
Function Calling et MCP peuvent être configurés ensemble dans session.tools. Ils ne peuvent pas être utilisés avec la recherche web (enable_search). Model Studio ne facture pas de frais supplémentaires pour les appels d’outils MCP. L’inférence du modèle reste soumise à sa tarification.
Découverte des outils
Après la configuration des serveurs MCP par le client avec session.update, le service Realtime découvre leurs outils de manière asynchrone :

opt indique une exécution lorsqu’une condition est remplie, alt indique des branches alternatives choisies selon une condition et par indique un traitement parallèle.
- Envoyez
session.updateavec les entrées MCP danssession.tools. - Traitez
mcp_list_tools.in_progress, qui peut arriver avantsession.updated.session.updatedconfirme l’acceptation de la configuration, mais pas la disponibilité des outils. - Le service découvre les outils. Il envoie
conversation.item.createdavec un élémentmcp_list_tools, suivi demcp_list_tools.completedoumcp_list_tools.failedavec le mêmeitem_id. L’élément contient les outils filtrés finaux ou une erreur.
response.create peuvent continuer pendant la découverte, mais seules les Responses créées après la fin de la découverte peuvent utiliser les outils correspondants.
Appels MCP et continuation
Lorsque le modèle sélectionne un outil MCP, le service Realtime exécute l’appel. Si une approbation est nécessaire, le client répond d’abord à la demande d’approbation :

- Le serveur crée un élément
mcp_callviaresponse.output_item.added. - Concaténez zéro ou plusieurs fragments
response.mcp_call_arguments.delta. La chaîne JSON complète deresponse.mcp_call_arguments.donefait autorité. - Si une approbation est nécessaire, traitez
conversation.item.createdavecitem.type="mcp_approval_request". Décidez d’autoriser ou non l’appel, puis répondez avecconversation.item.create,item.type="mcp_approval_response", l’item.idexact de l’approbation et le booléenapprove. L’approbation est obligatoire par défaut. - Les appels approuvés, ou configurés pour ne pas nécessiter d’approbation, émettent
response.mcp_call.in_progress. Le service exécute l’appel MCP, puis émetresponse.mcp_call.completedouresponse.mcp_call.failed. Un rejet ou un dépassement du délai d’approbation émetfailedsans exécution. - Traitez
response.output_item.donepour l’élément final de l’appel. Leresponse.doneparent arrive après que chaque élément MCP de cette Response a atteint un état final. Sonresponse.outputcontient les instantanés finaux : les appels réussis ontcompletedetoutput; les appels échoués ontfailedeterror. - Pour générer une réponse du modèle à partir des résultats MCP, envoyez un seul
response.createaprès leresponse.doneparent. Ne joignez pas les résultats MCP : ils sont déjà dans la conversation. N’utilisez pas le retour manuelfunction_call_outputpour ces appels MCP exécutés par le serveur.
Limites d’utilisation
Les contraintes MCP par défaut suivantes s’appliquent à chaque session :
| Élément | Valeur par défaut |
|---|---|
| Serveurs MCP | 8 |
| Outils MCP | 128 |
| Délai d’attente de la découverte des outils | 30 secondes |
| Délai d’attente de l’approbation | 60 secondes |
| Délai d’exécution des outils | 30 secondes |
| Taille d’une réponse du serveur en amont | 2 MB |
| Taille cumulée des résultats des outils | 8 MB |
| Nombre cumulé d’appels d’outils | 256 |
Gestion des erreurs
Si la négociation échoue, vérifiez le domaine, la région, l’espace de travail, l’API Key, le nom du modèle, son activation et ses autorisations. Après l’établissement de la connexion, localisez le problème à partir de l’événement error et consultez Codes d’erreur. Conservez l’ID de l’événement pour le diagnostic ; l’absence de réponse ne prouve pas que le protocole n’est pas pris en charge.