Skip to main content

Événements client Qwen-Audio-Realtime

Référence des événements client de l'API Qwen-Audio-Realtime.

Guide d'utilisation : Conversation vocale en temps réel (Qwen-Audio-Realtime). Pour la séquence d'interaction des événements, consultez Connexion WebSocket.
Cette page est la référence des événements de Qwen-Audio-Realtime. Les définitions d'événements reposent sur l'accès WebSocket. AOQ et WebRTC utilisent leurs canaux de données respectifs pour envoyer et recevoir les événements du modèle, et leurs pistes média pour transmettre les médias. Lisez d'abord Connexion WebSocket, Connexion WebRTC ou Connexion AOQ.
Pour l'utilisation du SDK WebSocket, consultez SDK Android, SDK iOS et SDK HarmonyOS. Pour sélectionner un modèle et un protocole, consultez Vue d'ensemble.

session.update

Description : Une fois la connexion établie, envoyez cet événement pour mettre à jour la configuration de session par défaut. N'incluez que les champs que vous souhaitez modifier ; les champs omis conservent leurs valeurs actuelles. Si un paramètre est invalide, le serveur renvoie une erreur. Si tous les paramètres sont valides, le serveur applique les modifications et renvoie la configuration complète.
turn_detection ne peut être modifié qu'avant l'envoi du premier audio (état IDLE).
typestring(obligatoire)
Type d'événement. Valeur fixe : session.update.
sessionobject(facultatif)
Configuration de la session.
modalitiesarray(facultatif)
Modalités de sortie du modèle. Valeurs autorisées :
  • ["text"] Texte uniquement.
  • ["audio", "text"] (default) Audio et texte combinés.
voicestring(facultatif)
Nom de la voix TTS. La valeur par défaut est longanqian_v3.1 pour 3.1 Plus/Flash et longanqian pour 3.0 Plus/Flash. Les voix système et les voix clonées sont prises en charge. Ce paramètre ne peut être défini que dans le premier session.update ; il est ignoré dans les appels suivants.
  • Voix système pour 3.1 Plus/Flash : Prend en charge longanqian_v3.1 et l'union des listes de voix de 3.1 TTS Plus et Flash. Pour la gamme complète, consultez Configuration de la voix.
  • Voix système pour 3.0 Plus/Flash : Valeurs disponibles : longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
  • Voix clonées : Créez une voix via l'API de clonage de voix et définissez ce paramètre sur le voice_id renvoyé. Pour plus de détails, consultez Configuration de la voix.
Après vous être connecté à qwen-audio-3.1-realtime-plus ou qwen-audio-3.1-realtime-flash, définissez la voix dans le premier session.update, par exemple :
{
    "type": "session.update",
    "session": {
        "voice": "longanqian_v3.1"
    }
}
speech_ratefloat(facultatif)
Contrôle la vitesse d'élocution de la sortie audio du modèle. Plage : [0.5, 2.0]. Valeur par défaut : 1.0. Les valeurs faibles ralentissent la parole ; les valeurs élevées l'accélèrent. Pris en charge par qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash.
enable_speech_emotionboolean(facultatif)
Indique s'il faut activer l'amélioration de l'émotion vocale. Lorsqu'elle est activée, la voix de la réponse présente des variations émotionnelles plus prononcées. Valeur par défaut : true. Valeurs autorisées : true et false.
instructionsstring(facultatif)
Instructions système définissant le rôle du modèle, son style de réponse et ses préférences comportementales. Elles s'appliquent à l'ensemble de la session.
input_audio_formatstring(facultatif)
Format audio d'entrée. Actuellement, seul pcm (16 kHz, 16 bits, mono) est pris en charge et constitue la valeur par défaut. Ne peut être modifié qu'avant l'envoi du premier audio (état IDLE).
output_audio_formatstring(facultatif)
Format audio de sortie. Actuellement, seul pcm (24 kHz, 16 bits, mono) est pris en charge et constitue la valeur par défaut.
input_audio_transcriptionobject(facultatif)
Configuration de la transcription de l'audio d'entrée.
languagestring(facultatif)
Langue source de l'audio d'entrée. S'applique à qwen-audio-3.1-realtime-plus et qwen-audio-3.1-realtime-flash. Les mots-clés instantanés fonctionnent également si vous omettez ce champ.Valeurs autorisées :
  • zh : chinois
  • en : anglais
  • ja : japonais
  • ko : coréen
  • vi : vietnamien
  • th : thaï
  • id : indonésien
  • ar : arabe
  • fr : français
  • de : allemand
  • es : espagnol
  • pt : portugais
  • ru : russe
  • it : italien
corpusobject(facultatif)
Configuration des mots-clés instantanés pour la transcription de l'audio d'entrée. S'applique à qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, qwen-audio-3.1-realtime-plus et qwen-audio-3.1-realtime-flash.
vocabularyobject
Objet associant des mots-clés à des poids entiers. Les mots-clés standards ont un poids compris entre 1 et 5. Plus le poids est élevé, plus la transcription a de chances d'utiliser le mot. Un poids de 50 désigne un super mot-clé. Vous pouvez inclure jusqu'à 50 super mots-clés et jusqu'à 2 000 mots-clés au total par mise à jour.L'envoi d'un autre objet vocabulary dans la même session remplace toute la liste précédente. Envoyez un objet vide {} pour effacer les mots-clés.
output_audioobject(facultatif)
Configuration de l'audio de sortie. S'applique à qwen-audio-3.1-realtime-plus et qwen-audio-3.1-realtime-flash.
languagestring(facultatif)
Langue cible de l'audio de sortie.Ce paramètre s'applique à la synthèse vocale (TTS). Le modèle fait de son mieux pour produire de la parole dans la langue cible, mais cela n'est pas garanti, et la langue du texte de réponse n'est pas modifiée. Pour générer du texte dans la langue cible, exprimez explicitement l'exigence dans le prompt, par exemple en précisant la langue de réponse dans instructions.Valeurs autorisées :
  • zh : chinois
  • en : anglais
  • fr : français
  • de : allemand
  • ja : japonais
  • ko : coréen
  • ru : russe
  • pt : portugais
  • th : thaï
  • id : indonésien
  • vi : vietnamien
  • es : espagnol
  • it : italien
  • ar : arabe
max_history_turnsinteger(facultatif)
Nombre maximal de tours de conversation (paires question-réponse) inclus dans une requête unique. Valeurs autorisées : 1 à 50. Valeur par défaut : 20.
enable_searchboolean(facultatif)
S'applique aux modèles qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus et qwen-audio-3.0-realtime-flash.Indique s'il faut activer la recherche web. Valeur par défaut : false. Lorsqu'elle est activée, le modèle décide d'effectuer ou non une recherche web en fonction de la requête en temps réel.Vous pouvez définir enable_search sur true et configurer des outils Function Calling via tools dans la même session.
search_optionsobject(facultatif)
Configuration de la recherche web. Ce paramètre ne prend effet que si enable_search est défini sur true.
enable_sourceboolean(facultatif)
Indique s'il faut renvoyer les sources des résultats de recherche. Définissez ce paramètre sur true pour renvoyer les sources.
toolsarray(facultatif)
Définitions d'outils pour le Function Calling. Une fois configurés, le modèle décide d'appeler ou non un outil en fonction des entrées utilisateur.
typestring(obligatoire)
Valeur fixe : function.
functionobject
namestring(obligatoire)
Nom de la fonction outil.
descriptionstring(facultatif)
Description de la fonction outil. Le modèle s'en sert pour déterminer s'il doit appeler l'outil.
parametersobject(facultatif)
Description des paramètres d'entrée de la fonction outil. Le modèle les utilise pour extraire les paramètres requis. Omettez ce champ si la fonction ne prend aucun paramètre.
typestring(obligatoire)
Valeur fixe : object.
propertiesobject(facultatif)
Décrit le nom, le type de données et la description de chaque paramètre.
requiredarray(facultatif)
Spécifie les paramètres obligatoires.
turn_detectionobject|null(facultatif)
Les champs de détection de tour décrits ci-dessous s'appliquent à qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus et qwen-audio-3.0-realtime-flash.Configuration de la détection de tour de parole. Pour passer en mode push-to-talk, définissez ce champ sur null. En mode push-to-talk, l'audio doit être validé manuellement et l'inférence déclenchée manuellement. Si ce champ n'est pas fourni, le VAD est activé avec ses paramètres par défaut.
typestring(facultatif)
Type de VAD. Valeurs autorisées :
  • server_vad (par défaut) : Détecte le début et la fin de la parole à partir de caractéristiques acoustiques et déclenche automatiquement l'inférence.
  • smart_turn : Mode de détection de tour intelligent combinant perception acoustique et compréhension sémantique pour déterminer les limites des tours. Les hésitations comme « euh » ou « hum » ne déclenchent pas de nouveau tour et n'interrompent pas la lecture du modèle.
  • smart_turn_v2 (recommandé) : S'appuie sur smart_turn pour mieux comprendre le contexte de conversation et l'intention d'interaction dans les environnements multi-locuteurs. Réduit les réponses ou interruptions non souhaitées causées par des tierces personnes ou des interventions sans rapport.
thresholdfloat(facultatif)
Sensibilité du VAD. S'applique à server_vad, smart_turn et smart_turn_v2. Les valeurs faibles augmentent la sensibilité du VAD, facilitant la détection de sons ténus (y compris le bruit de fond) comme parole. Les valeurs élevées réduisent la sensibilité, exigeant une parole plus claire et plus forte pour déclencher la détection.Plage : [-1.0, 1.0]. Valeur par défaut : 0.5.
silence_duration_msinteger(facultatif)
Durée minimale de silence (en millisecondes) après la fin de la parole avant de déclencher une réponse du modèle. Efficace uniquement en mode server_vad (ignoré en modes smart_turn / smart_turn_v2). Les valeurs faibles produisent des réponses plus rapides mais peuvent provoquer des déclenchements intempestifs lors de courtes pauses.Plage : [200, 6000]. Valeur par défaut : 800. Plage recommandée pour les conversations : 400-800.
voiceprint_audio_urlsarray(facultatif)
Efficace uniquement en modes smart_turn / smart_turn_v2. Liste d'URL accessibles publiquement pointant vers des échantillons audio préenregistrés de l'utilisateur cible, utilisés pour l'amélioration du locuteur. Une fois enregistrés, le modèle se verrouille sur le locuteur cible pendant les conversations duplex, ignorant efficacement les autres voix et le bruit de fond. Maximum 5 URL. Exigences de format audio : PCM 16 kHz ou WAV.
Ce paramètre ne peut être configuré que dans le premier événement session.update. Il est ignoré dans les événements session.update ultérieurs.
  • Configuration de base
  • Configuration des langues
  • Mots-clés instantanés
  • Function Calling
  • Enregistrement d'empreinte vocale
Les exemples ci-dessous s'appliquent à qwen-audio-3.1-realtime-plus et qwen-audio-3.1-realtime-flash et sélectionnent explicitement la voix système longanqian_v3.1.
{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian_v3.1",
        "speech_rate": 1.2,
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

input_audio_buffer.append

Description : Pour l'accès WebSocket, ajoute des données audio au tampon d'entrée. Envoyez les données en continu à de courts intervalles, par exemple une trame toutes les 20~40 ms. Le serveur n'accuse pas réception de cet événement.
typestring(obligatoire)
Type d'événement. Valeur fixe : input_audio_buffer.append.
audiostring(obligatoire)
Données audio encodées en Base64.
{
    "type": "input_audio_buffer.append",
    "audio": "<Base64-encoded audio data>"
}

input_audio_buffer.commit

Description : Mode push-to-talk uniquement. Valide l'audio mis en tampon en tant que message utilisateur. Cela ne déclenche pas automatiquement l'inférence. Envoyez response.create pour déclencher l'inférence manuellement. Cet événement est ignoré en modes server_vad, smart_turn et smart_turn_v2.
typestring(obligatoire)
Type d'événement. Valeur fixe : input_audio_buffer.commit.
{
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

Description : Pour l'accès WebSocket, cet événement ne prend effet qu'en mode push-to-talk. Il efface du tampon l'audio non validé. Cet événement est ignoré en modes server_vad / smart_turn / smart_turn_v2. Le serveur répond par un événement input_audio_buffer.cleared.
typestring(obligatoire)
Type d'événement. Valeur fixe : input_audio_buffer.clear.
{
    "type": "input_audio_buffer.clear"
}

conversation.item.create

Description : Insère un élément de conversation dans le contexte de conversation. Utilisez cet événement pour injecter un historique ou ajouter du contenu textuel, ou pour renvoyer des résultats de Function Calling.
Si item.id existe déjà dans la conversation, une erreur est renvoyée et l'élément n'est pas créé.
typestring(obligatoire)
Type d'événement. Valeur fixe : conversation.item.create.
previous_item_idstring(facultatif)
Spécifie l'élément de conversation après lequel le nouvel élément est inséré. S'il n'est pas fourni, l'élément est ajouté à la fin de la conversation.
itemobject(obligatoire)
Élément de conversation à créer.
idstring(facultatif)
Identifiant unique de l'élément de conversation. S'il n'est pas fourni, le serveur en génère un automatiquement. Une erreur est renvoyée si l'ID spécifié existe déjà dans la conversation.
typestring(obligatoire)
Type d'élément de conversation. Valeurs autorisées :
  • message : Message de conversation standard.
  • function_call : Requête d'appel de fonction. Généralement générée par le serveur, mais les clients peuvent aussi l'utiliser pour injecter un historique.
  • function_call_output : Résultat d'exécution d'outil. Après réception d'un function_call, le client exécute l'outil et renvoie le résultat via ce type.
rolestring(requis pour le type message)
Rôle du message. Valeurs autorisées : system, user, assistant.
contentarray(requis pour le type message)
Liste des éléments de contenu du message. Chaque élément contient un champ type et les champs de données correspondants.
systeminput_text : Message système. Champ requis : text.user
  • input_text : Entrée texte utilisateur. Champ requis : text.
  • input_audio : Entrée audio utilisateur. Champ requis : audio (encodé en Base64).
assistantoutput_text : Sortie texte de l'assistant. Champ requis : text.
call_idstring(requis pour les types function_call / function_call_output)
Identifiant unique de l'appel de fonction, utilisé pour corréler les requêtes et les résultats.
namestring(requis pour le type function_call)
Nom de la fonction à appeler.
argumentsstring(requis pour le type function_call)
Paramètres de l'appel de fonction au format chaîne JSON.
outputstring(requis pour le type function_call_output)
Résultat de l'exécution de l'outil au format chaîne JSON.
  • Message texte utilisateur
  • Résultat Function Calling
Injection d'un message texte utilisateur :
{
    "type": "conversation.item.create",
    "previous_item_id": "item_xxx",
    "item": {
        "id": "my_item_001",
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "Please summarize our last conversation"
            }
        ]
    }
}

conversation.item.retrieve

Description : Récupère un élément de conversation stocké sur le serveur. Le contenu de type audio dans la réponse ne contient que la transcription (transcript), et non les données audio d'origine.
typestring(obligatoire)
Type d'événement. Valeur fixe : conversation.item.retrieve.
item_idstring(obligatoire)
ID de l'élément de conversation à récupérer. Le serveur renvoie le résultat dans un événement conversation.item.retrieved.
{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

conversation.item.delete

Description : Supprime un élément de conversation du contexte de conversation. Le serveur confirme la suppression par un événement conversation.item.deleted.
typestring(obligatoire)
Type d'événement. Valeur fixe : conversation.item.delete.
item_idstring(obligatoire)
ID de l'élément de conversation à supprimer.
{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

response.create

Description : Déclenche l'inférence du modèle. Le comportement varie selon le mode :
  • Mode push-to-talk : Doit être appelé manuellement. Validez d'abord l'audio mis en tampon avec input_audio_buffer.commit, ou renvoyez un résultat function_call_output avant de déclencher. Ne peut pas être appelé pendant la génération d'une réponse.
  • Mode server_vad : Généralement déclenché automatiquement par le serveur. Les clients peuvent aussi l'appeler manuellement lorsqu'aucune réponse n'est en cours de génération. Ne peut pas être appelé pendant la génération d'une réponse.
  • Modes smart_turn / smart_turn_v2 : Peut être appelé en attendant le prochain tour utilisateur. Ne peut pas être appelé pendant un tour actif (entre input_audio_buffer.speech_started et response.done).
Le champ facultatif response remplace les valeurs par défaut de la session pour le cycle d'inférence en cours. Dans les scénarios de Function Calling, après que le client a renvoyé un function_call_output, cet événement déclenche le second cycle d'inférence.
En modes server_vad, smart_turn et smart_turn_v2, les inférences déclenchées manuellement peuvent toujours être interrompues par une nouvelle prise de parole.
typestring(obligatoire)
Type d'événement. Valeur fixe : response.create.
responseobject(facultatif)
Remplace les valeurs par défaut de la session pour le cycle d'inférence en cours. S'il n'est pas fourni, la configuration de session actuelle est utilisée.
modalitiesarray(facultatif)
Remplace les modalités de sortie pour le cycle en cours. Les valeurs autorisées sont identiques à celles de session.update modalities.
voicestring(facultatif)
Remplace la voix TTS pour le cycle en cours.
{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

response.cancel

Description : Annule l'inférence en cours. Tout texte généré jusqu'à présent est enregistré dans la liste des éléments. Le serveur renvoie ensuite un événement response.done avec status=cancelled. Une erreur est renvoyée si aucune inférence n'est en cours.
typestring(obligatoire)
Type d'événement. Valeur fixe : response.cancel.
{
    "type": "response.cancel"
}