Aperçu de la connexion WebSocket - Alibaba Cloud Model Studio

Découvrir les points de terminaison WebSocket, l'authentification, les flux d'interaction Realtime et Inference, ainsi que les événements spécifiques aux modèles.

Prérequis

Activer le modèle ou l'application cible et confirmer ses régions prises en charge.
Obtenir une clé API pour la région et l'espace de travail que vous utiliserez. Voir Authentification par jeton.
Obtenir votre ID d'espace de travail si vous utilisez un domaine spécifique à l'espace de travail.

Pour la sélection du protocole et les modèles pris en charge, voir Aperçu de l'API Realtime.

En-têtes de requête

Définir Authorization dans la requête de handshake WebSocket. Utiliser les autres en-têtes comme décrit dans la référence des paramètres du modèle cible.

En-tête	Obligatoire	Description
`Authorization`	Oui	Transmettre la clé API sous la forme `Bearer <API_KEY>`.
`user-agent`	Non	Identifie le client.
`X-DashScope-WorkSpace`	Spécifique au modèle	Spécifie un ID d'espace de travail. Consulter la référence des en-têtes spécifiques au modèle pour l'utilisation.
`X-DashScope-DataInspection`	Spécifique au modèle	Configure l'inspection des données. Consulter la référence des en-têtes spécifiques au modèle pour les valeurs prises en charge et l'applicabilité.

Points de terminaison

Utiliser wss:// et sélectionner le chemin d'API et l'emplacement du nom du modèle pour votre modèle cible. Le tableau ci-dessous liste les méthodes de connexion par modèle. Pour les modèles et régions pris en charge, consulter la documentation correspondante du modèle.

Famille de modèles	Chemin d'API	Emplacement du nom du modèle
Qwen-Omni-Realtime	`/api-ws/v1/realtime`	Paramètre de requête URL `model`
Qwen-Audio-TTS/CosyVoice	`/api-ws/v1/inference`	`payload.model` dans `run-task`
Qwen-TTS-Realtime	`/api-ws/v1/realtime`	Paramètre de requête URL `model`
Qwen-Audio-ASR/Fun-ASR/Paraformer	`/api-ws/v1/inference`	`payload.model` dans `run-task`
Qwen-ASR-Realtime	`/api-ws/v1/realtime`	Paramètre de requête URL `model`
Qwen-Audio-Realtime	`/api-ws/v1/realtime`	Paramètre de requête URL `model`
Qwen-LiveTranslate-Realtime	`/api-ws/v1/realtime`	Paramètre de requête URL `model`

Domaines spécifiques à l'espace de travail :

Région	Domaine spécifique à l'espace de travail
Chine (Pékin)	`{WorkspaceId}.cn-beijing.maas.aliyuncs.com`
Singapour	`{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`

Remplacer {WorkspaceId} par votre ID d'espace de travail. Exemples :

wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtime
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference

Qwen-TTS-Realtime prend également en charge les domaines publics dashscope.aliyuncs.com pour Pékin et dashscope-intl.aliyuncs.com pour Singapour, avec le même chemin /api-ws/v1/realtime. La clé API doit correspondre à la région.

Flux d'interaction courants

/api-ws/v1/realtime utilise un protocole basé sur les sessions, tandis que /api-ws/v1/inference utilise un protocole basé sur les tâches.

Protocole Realtime

Après la connexion, le client configure la session avec session.update et attend session.updated avant d'envoyer des entrées. Le modèle cible détermine comment valider l'entrée, déclencher une réponse et terminer la session.

Client → Realtime API : Handshake WebSocket avec Authorization et model.
Realtime API → Client : HTTP 101 et session.created.
Client → Realtime API : session.update. Realtime API → Client : session.updated.
Dans la boucle d'entrée/sortie, sélectionner la branche d'entrée : pour l'audio, Client → Realtime API : input_audio_buffer.append ; pour l'entrée texte Qwen-TTS, Client → Realtime API : input_text_buffer.append.
Validation manuelle facultative : Client → Realtime API : input_audio_buffer.commit ou input_text_buffer.commit, sélectionné selon le type d'entrée.
Pour les modèles nécessitant une réponse explicite, Client → Realtime API : response.create.
Realtime API → Client : événements textuels / response.audio.delta.
Achèvement facultatif de la réponse, à l'exclusion des modèles ASR uniquement : Realtime API → Client : response.done. La boucle d'entrée/sortie peut continuer.
Pour les modèles prenant en charge un événement de fin, Client → Realtime API : session.finish ; Realtime API → Client : session.finished.
Client → Realtime API : Fermer la connexion WebSocket.

Étapes détaillées

Se connecter : Spécifier le modèle dans le paramètre de requête model de l'URL et inclure la clé API dans les en-têtes de requête. Après un handshake réussi, le serveur envoie session.created.
Configurer la session : Envoyer session.update pour configurer les formats audio pris en charge, les modalités de sortie, les voix ou les paramètres de détection de la parole, puis attendre session.updated. Consulter la référence des événements clients spécifiques au modèle pour les paramètres de session pris en charge.
Envoyer des entrées : Envoyer de l'audio encodé en Base64 avec input_audio_buffer.append. Pour Qwen-TTS, envoyer du texte avec input_text_buffer.append. Les modèles qui prennent en charge l'entrée d'image utilisent input_image_buffer.append ; suivre les exigences de synchronisation d'image et d'audio du modèle.
Valider et recevoir des résultats : Dans les modes automatiques, le serveur déclenche le traitement. Dans les modes manuels, envoyer input_audio_buffer.commit ou input_text_buffer.commit selon le type d'entrée. La nécessité d'utiliser également response.create et les événements de résultat à gérer dépendent du modèle. Voir la comparaison ci-dessous.
Terminer la session : Pour les modèles qui prennent en charge un événement de fin, envoyer session.finish et attendre session.finished ainsi que les résultats restants. Pour les autres modèles, fermer la connexion WebSocket après avoir reçu les résultats. response.done marque la fin d'une réponse, et non celle de la connexion. Pour les modèles ASR uniquement, les événements de fin de transcription marquent la fin de la reconnaissance.

Protocole d'inférence

Le client envoie run-task et attend task-started avant de transmettre l'entrée. La reconnaissance vocale utilise des trames audio binaires ; la synthèse vocale envoie du texte avec continue-task. Lorsque l'entrée se termine, envoyer finish-task et attendre task-finished.

Client → Inference API : Handshake WebSocket avec Authorization.
Inference API → Client : HTTP 101.
Client → Inference API : run-task avec payload.model et task_id. Inference API → Client : task-started.
Dans la boucle d'entrée/sortie, la branche de reconnaissance vocale envoie des trames audio binaires du Client vers Inference API. Inference API retourne result-generated au Client.
Dans la branche de synthèse vocale, Client → Inference API : continue-task avec texte et task_id. Inference API → Client : trames audio binaires et result-generated si fourni.
Lorsque la boucle d'entrée/sortie se termine, Client → Inference API : finish-task avec le même task_id.
Inference API → Client : Résultats restants et task-finished.
Client → Inference API : Fermer ou réutiliser la connexion selon la prise en charge par le modèle.

Étapes détaillées

Se connecter : Utiliser /api-ws/v1/inference et inclure la clé API dans les en-têtes de requête.
Démarrer une tâche : Envoyer run-task, en spécifiant le modèle dans payload.model et les paramètres tels que le format d'entrée. Générer un header.task_id unique et attendre task-started.
Envoyer des entrées et recevoir des résultats :
- Reconnaissance vocale : Envoyer des trames audio binaires et recevoir les résultats de reconnaissance via result-generated.
- Synthèse vocale : Envoyer du texte dans payload.input.text de continue-task et recevoir des trames audio binaires. Le modèle peut également retourner des informations telles que des horodatages via result-generated.
Terminer la tâche : Après avoir envoyé finish-task, continuer à recevoir les résultats restants jusqu'à l'arrivée de task-finished. Tous les événements run-task, continue-task et finish-task pour la même tâche doivent utiliser le même header.task_id. Ensuite, fermer la connexion ou la réutiliser si cela est pris en charge par le modèle.

Différences entre les modèles

Modèles Realtime

Le tableau ci-dessous résume les déclencheurs d'entrée et la fin de session. Pour tous les types de VAD pris en charge, les formats audio et les autres valeurs de paramètres, consulter les références d'événements spécifiques au modèle.

Modèle	Déclencheur d'entrée et de réponse	Terminaison
Qwen3.8-Omni / Qwen3.5-Omni	Les modes VAD déclenchent automatiquement les réponses. En mode manuel, envoyer `input_audio_buffer.commit` suivi de `response.create`.	Fermer la connexion après avoir reçu les résultats.
Qwen-TTS-Realtime	`server_commit` valide le texte automatiquement. En mode `commit`, envoyer `input_text_buffer.commit` ; `response.create` n'est pas requis.	`session.finish → session.finished`
Qwen-ASR-Realtime	Le mode VAD traite automatiquement les entrées. En mode manuel, envoyer `input_audio_buffer.commit` ; `response.create` n'est pas requis.	`session.finish → session.finished`
Qwen-Audio-Realtime	Les modes automatiques détectent les tours de parole côté serveur. En mode manuel, envoyer `input_audio_buffer.commit` suivi de `response.create`.	Fermer la connexion après avoir reçu les résultats.
Qwen3.8-LiveTranslate	Configurer les modalités de sortie avec `output_modalities` et la détection des tours de parole avec `audio.input.turn_detection`. Diffuser l'audio en continu et envoyer `session.finish` lorsque l'entrée se termine.	`session.finish → session.finished`
Qwen3.5-LiveTranslate	Configurer la session avec `modalities` et `turn_detection`. En mode manuel, `input_audio_buffer.commit` déclenche une réponse sans `response.create`.	`session.finish → session.finished`

Les événements de sortie principaux sont listés ci-dessous. Les événements retournés dépendent des modalités de sortie configurées.

Modèle	Événements de sortie principaux
Qwen-Omni-Realtime	`response.text.delta` / `response.audio_transcript.delta` / `response.audio.delta` / `response.done`
Qwen-TTS-Realtime	`response.audio.delta` / `response.done`
Qwen-ASR-Realtime	`conversation.item.input_audio_transcription.text` / `conversation.item.input_audio_transcription.completed`
Qwen-Audio-Realtime	`response.audio_transcript.delta` / `response.audio.delta` / `response.done`
Qwen3.8-LiveTranslate	`response.text.delta` / `response.audio_transcript.delta` / `response.audio.delta` / `response.done`
Qwen3.5-LiveTranslate	`response.text.text` / `response.audio_transcript.text` / `response.audio.delta` / `response.done`

RemarqueLes noms des événements de traduction dépendent de la version du modèle : Qwen3.8-LiveTranslate utilise .delta, tandis que Qwen3.5-LiveTranslate utilise .text. Par exemple, les transcriptions audio traduites utilisent respectivement response.audio_transcript.delta et response.audio_transcript.text.

Modèles d'inférence

Qwen-Audio-TTS/CosyVoice utilise le flux de tâches run-task → task-started → continue-task → finish-task → task-finished. La reconnaissance vocale Qwen-Audio-ASR/Fun-ASR/Paraformer envoie des trames audio binaires après task-started. Les deux types signalent les erreurs de tâche via task-failed.

Guides d'intégration spécifiques aux modèles

Omni en temps réel

Omni en temps réel

Synthèse vocale en temps réel

Qwen-Audio-TTS

CosyVoice

Qwen-TTS-Realtime

Sambert

Sambert SDK HarmonyOS

Reconnaissance vocale en temps réel

Qwen-Audio-ASR-Message

Qwen-Audio-ASR-Streaming

Fun-ASR-Realtime

Qwen-ASR-Realtime

Paraformer

Conversation vocale en temps réel

Qwen-Audio-Realtime

Traduction audio et vidéo en temps réel

Qwen-Livetranslate-Realtime

Gestion des erreurs

Échec du handshake : Utiliser le statut HTTP et le message d'erreur pour vérifier le point de terminaison, la clé API, l'espace de travail et les autorisations du modèle. Pour 401/403, vérifier d'abord l'authentification.
Modèle indisponible ou non activé : Vérifier le nom du modèle, l'activation du service et la région.
Erreurs Realtime : Gérer les événements error et lire leur type et leur message. Ajuster le type d'événement ou les paramètres dans la requête en fonction du message d'erreur.
Erreurs d'inférence : Un événement task-failed indique que la tâche a échoué. Lire header.error_code et header.error_message pour connaître la cause.

Après avoir corrigé la configuration ou géré une interruption réseau, se reconnecter et configurer une nouvelle session ou démarrer une nouvelle tâche selon les exigences du protocole. Voir Codes d'erreur.