Client events for the Qwen-Audio Realtime API - Alibaba Cloud Model Studio

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

Guide utilisateur : Chat audio en temps réel (Qwen-Audio-Realtime). Pour les séquences d'interaction des événements, consultez la rubrique API WebSocket.

session.update

Description : Une fois la connexion établie, envoyez cet événement pour modifier la configuration de session par défaut. N'incluez que les champs à changer ; les champs omis conservent leur valeur actuelle. Si un paramètre est invalide, le serveur renvoie une erreur. Si tous les paramètres sont valides, le serveur applique les modifications et retourne la configuration complète.

RemarqueLe paramètre turn_detection ne peut être modifié qu'avant l'envoi du premier flux audio (état IDLE).

typestring(obligatoire)

Type d'événement. Valeur fixe : session.update.

{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

Configuration des langues (qwen-audio-3.1-realtime-plus)

Après vous être connecté à qwen-audio-3.1-realtime-plus, vous pouvez envoyer l'événement session.update suivant pour définir le chinois comme langue source de l'audio d'entrée et l'anglais comme langue cible de l'audio de sortie.

{
    "type": "session.update",
    "session": {
        "input_audio_transcription": {
            "language": "zh"
        },
        "output_audio": {
            "language": "en"
        }
    }
}

Function Calling :

{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get weather for a specified city",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string",
                                "title": "City"
                            }
                        },
                        "required": ["city"]
                    }
                }
            }
        ],
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

Enregistrement d'empreinte vocale (voiceprint_audio_urls) :

{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn",
            "voiceprint_audio_urls": [
                "https://example.com/speaker1.pcm",
                "https://example.com/speaker2.wav"
            ]
        }
    }
}

sessionobject (facultatif)

Configuration de la session.

Propriétés

modalitiesarray (facultatif)

Modalités de sortie du modèle. Valeurs autorisées :

["text"]

Texte uniquement.
["audio", "text"] (par défaut)

Audio et texte combinés.

voicestring (facultatif)

Nom de la voix TTS. Valeur par défaut : longanqian. Deux catégories de voix sont prises en charge. Ce paramètre ne peut être défini que lors du premier appel session.update ; il est ignoré dans les appels suivants.

Voix système : Valeurs disponibles : longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
Voix clonées : créées via l'API Voice Cloning. Transmettez la valeur voice_id retournée comme valeur de ce paramètre. Pour plus de détails, consultez la rubrique Configuration de la voix.

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 le format pcm (16 kHz, 16 bits, mono) est pris en charge et utilisé par défaut. La modification n'est possible qu'avant l'envoi du premier flux audio (état IDLE).

output_audio_formatstring (facultatif)

Format audio de sortie. Seul le format pcm (24 kHz, 16 bits, mono) est actuellement pris en charge et configuré par défaut.

input_audio_transcriptionobject (facultatif)

Configuration de la transcription de l'audio d'entrée. S'applique à qwen-audio-3.1-realtime-plus.

Propriétés

languagestring (facultatif)

Langue source de l'audio d'entrée.

Valeurs autorisées :

zh : chinois
en : anglais
ja : japonais
ko : coréen
vi : vietnamien
th : thaï
id : indonésien
ms : malais
tl : filipino
hi : hindi
ar : arabe
fr : français
de : allemand
es : espagnol
pt : portugais
ru : russe
it : italien
nl : néerlandais
sv : suédois
da : danois
fi : finnois
no : norvégien
el : grec
pl : polonais
cs : tchèque
hu : hongrois
ro : roumain
bg : bulgare
hr : croate
sk : slovaque

output_audioobject (facultatif)

Configuration de l'audio de sortie. S'applique à qwen-audio-3.1-realtime-plus.

Propriétés

languagestring (facultatif)

Langue cible de l'audio de sortie.

Ce paramètre agit sur la synthèse vocale (TTS) : le modèle essaie de produire un audio dans la langue cible, sans garantie de résultat, et la langue du texte de réponse n'est pas modifiée. Pour obtenir un texte dans la langue cible, indiquez-le explicitement 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
ms : malais
fil : filipino
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 : de 1 à 50. Valeur par défaut : 20.

toolsarray (facultatif)

Définitions des 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.

Propriétés

typestring(obligatoire)

Valeur fixe : function.

function.namestring(obligatoire)

Nom de la fonction outil.

function.descriptionstring (facultatif)

Description de la fonction outil. Le modèle s'en sert pour déterminer s'il doit invoquer l'outil.

function.parametersobject (facultatif)

Description des paramètres d'entrée de la fonction outil. Le modèle utilise ces informations pour extraire les paramètres requis. Omettez ce champ si la fonction ne prend aucun paramètre.

Propriétés

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)

Configuration de la détection de tour de parole. Pour passer en mode push-to-talk, affectez la valeur null à ce champ. Dans ce mode, vous devez valider manuellement l'audio et déclencher explicitement l'inférence. En l'absence de cette valeur, le VAD est activé avec ses paramètres par défaut.

Propriétés

typestring (facultatif)

Type de VAD. Valeurs autorisées :

server_vad (par défaut) : Détecte le début et la fin de la parole selon des caractéristiques acoustiques, puis déclenche automatiquement l'inférence.
smart_turn : Mode de détection intelligent combinant perception acoustique et compréhension sémantique pour identifier les limites des tours de parole. Les hésitations telles que « euh » ou « hum » ne provoquent ni nouveau tour ni interruption de la lecture du modèle.

thresholdfloat (facultatif)

Sensibilité du VAD. Ce réglage n'est effectif qu'en mode server_vad (ignoré en mode smart_turn). Des valeurs faibles accroissent la sensibilité, facilitant la détection de sons ténus (y compris le bruit ambiant) comme de la parole. Des valeurs élevées réduisent cette sensibilité, exigeant une voix plus claire et plus forte pour activer 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. Paramètre actif uniquement en mode server_vad (ignoré en mode smart_turn). Une valeur basse accélère les réponses mais risque de 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 mode smart_turn. Liste d'URL accessibles publiquement pointant vers des échantillons audio préenregistrés de l'utilisateur cible, servant à l'amélioration du locuteur. Après enregistrement, le modèle se verrouille sur le locuteur cible durant les conversations duplex, filtrant efficacement les autres voix et le bruit de fond. Maximum 5 URL. Formats audio requis : PCM 16 kHz ou WAV.

ImportantCe paramètre ne peut être configuré que lors du premier événement session.update. Il est ignoré dans les événements session.update ultérieurs.

input_audio_buffer.append

Description : Ajoute des données audio au tampon d'entrée. Envoyez cet événement de manière continue et à haute fréquence, par exemple un fragment toutes les 20 à 40 ms. Le serveur n'envoie aucun accusé de réception pour cet événement.

typestring(obligatoire)

Type d'événement. Valeur fixe : input_audio_buffer.append.

{
    "type": "input_audio_buffer.append",
    "audio": "<Base64-encoded audio data>"
}

audiostring(obligatoire)

Données audio encodées en Base64.

input_audio_buffer.commit

Description : Mode push-to-talk uniquement. Valide l'audio mis en tampon comme message utilisateur. Cette action ne déclenche pas automatiquement l'inférence. Envoyez l'événement response.create pour lancer l'inférence manuellement.

Cet événement est ignoré dans les modes server_vad et smart_turn.

typestring(obligatoire)

Type d'événement. Valeur fixe : input_audio_buffer.commit.

{
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

Description : Mode push-to-talk uniquement. Efface l'audio non validé présent dans le tampon. Cet événement est ignoré dans les modes server_vad et smart_turn. 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 dans le contexte de conversation. Utilisez cet événement pour injecter un historique, ajouter du contenu textuel ou restituer les résultats d'un Function Calling.

RemarqueSi l'identifiant 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.

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

Restitution d'un résultat de Function Calling :

{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"sunny\"}"
    }
}

previous_item_idstring (facultatif)

Indique l'élément de conversation après lequel insérer le nouvel élément. Sans cette précision, l'élément est ajouté à la fin de la conversation.

itemobject(obligatoire)

Élément de conversation à créer.

Propriétés

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 survient 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 produite par le serveur, mais les clients peuvent aussi l'utiliser pour injecter un historique.
function_call_output : Résultat d'exécution d'outil. Suite à la 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 constituant le message. Chaque élément comporte un champ type ainsi que les champs de données correspondants.

Types de contenu pris en charge par rôle

system

input_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).

assistant

output_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, permettant de corréler les requêtes et leurs 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 sous forme de chaîne JSON.

outputstring (requis pour le type function_call_output)

Résultat de l'exécution de l'outil sous forme de chaîne JSON.

conversation.item.retrieve

Description : Récupère un élément de conversation stocké côté serveur. Pour les contenus audio, la réponse ne contient que la transcription (transcript), sans les données audio brutes.

typestring(obligatoire)

Type d'événement. Valeur fixe : conversation.item.retrieve.

{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

item_idstring(obligatoire)

ID de l'élément de conversation à récupérer. Le serveur renvoie le résultat via un événement conversation.item.retrieved.

conversation.item.delete

Description : Supprime un élément du contexte de conversation. Le serveur confirme cette suppression par un événement conversation.item.deleted.

typestring(obligatoire)

Type d'événement. Valeur fixe : conversation.item.delete.

{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

item_idstring(obligatoire)

ID de l'élément de conversation à supprimer.

response.create

Description : Déclenche l'inférence du modèle. Le comportement varie selon le mode actif :

Mode push-to-talk : Appel manuel obligatoire. Validez d'abord l'audio en tampon avec input_audio_buffer.commit, ou fournissez un résultat function_call_output avant de déclencher l'inférence. Impossible d'appeler cette commande pendant la génération d'une réponse.
Mode server_vad : Généralement déclenché automatiquement par le serveur. Les clients peuvent toutefois l'invoquer manuellement lorsqu'aucune réponse n'est en cours de génération. L'appel est impossible durant la production d'une réponse.
Mode smart_turn : Peut être appelé en attendant le prochain tour de parole utilisateur. L'appel est interdit pendant un tour actif (entre input_audio_buffer.speech_started et response.done).

Le champ facultatif response remplace les paramètres par défaut de la session pour le cycle d'inférence en cours. Dans le cadre d'un Function Calling, après que le client a renvoyé un function_call_output, cet événement lance le second cycle d'inférence.

RemarqueDans les modes server_vad et smart_turn, toute inférence déclenchée manuellement reste susceptible d'être interrompue par une nouvelle prise de parole.

typestring(obligatoire)

Type d'événement. Valeur fixe : response.create.

{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

responseobject (facultatif)

Remplace les valeurs par défaut de la session pour le cycle d'inférence actuel. En l'absence de ce paramètre, la configuration de session en vigueur est utilisée.

Propriétés

modalitiesarray (facultatif)

Remplace les modalités de sortie pour le cycle en cours. Les valeurs valides sont identiques à celles du champ session.update modalities.

voicestring (facultatif)

Remplace la voix TTS pour le cycle actuel.

response.cancel

Description : Annule l'inférence en cours. Tout texte déjà généré est conservé dans la liste des éléments. Le serveur renvoie ensuite un événement response.done avec le statut status=cancelled.

Une erreur est renvoyée si aucune inférence n'est active.

typestring(obligatoire)

Type d'événement. Valeur fixe : response.cancel.

{
    "type": "response.cancel"
}