Eventos de cliente para la API en tiempo real de Qwen-Audio - Alibaba Cloud Model Studio

Referencia de eventos de cliente para la API en tiempo real de Qwen-Audio.

Guía del usuario: Chat de audio en tiempo real (Qwen-Audio-Realtime). Para secuencias de interacción de eventos, consulte API de WebSocket.

session.update

Descripción: Después de establecer una conexión, envíe este evento para actualizar la configuración predeterminada de la sesión. Incluya solo los campos que want cambiar; los campos omitidos conservan sus valores actuales. Si algún parámetro no es válido, el servidor devuelve un error. Si todos los parámetros son válidos, el servidor aplica los cambios y devuelve la configuración completa.

Notaturn_detection solo puede modificarse antes de enviar el primer audio (estado IDLE).

typestring(obligatorio)

Tipo de evento. Valor fijo: session.update.

sessionobject (opcional)

Configuración de la sesión.

Propiedades

modalitiesarray (opcional)

Modalidades de salida para el modelo. Valores válidos:

["text"]

Solo texto.
["audio", "text"] (predeterminado)

Tanto texto como audio.

voicestring (opcional)

Nombre de la voz TTS. El valor predeterminado es longanqian_v3.1 para 3.1 Plus y longanqian para 3.0 Plus/Flash. Se admiten voces del sistema y voces clonadas. Solo puede configurarse en el primer session.update; se ignora en llamadas subsiguientes.

Voces adicionales del sistema para 3.1 Plus: longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1, cally_v3.1.
Voces del sistema compartidas por 3.1 Plus y 3.0 Plus/Flash: Valores disponibles: longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
Voces clonadas: creadas mediante la API de clonación de voz. Pase el voice_id devuelto como valor de este parámetro. Para más detalles, consulte Configuración de voz.

Después de conectarse a qwen-audio-3.1-realtime-plus, configure la voz en el primer session.update, por ejemplo:

{
    "type": "session.update",
    "session": {
        "voice": "longanqian_v3.1"
    }
}

enable_speech_emotionboolean (opcional)

Especifica si se debe habilitar la mejora de emoción en el habla. Cuando está habilitada, la voz de respuesta exhibe variaciones emocionales más pronunciadas. Valor predeterminado: true. Valores válidos: true y false.

instructionsstring (opcional)

Instrucciones del sistema que definen el rol del modelo, el estilo de respuesta y las preferencias de comportamiento. Aplica a toda la sesión.

input_audio_formatstring (opcional)

Formato de audio de entrada. Actualmente solo se admite pcm (16 kHz, 16 bits, mono) y es el valor predeterminado. Solo puede modificarse antes de enviar el primer audio (estado IDLE).

output_audio_formatstring (opcional)

Formato de audio de salida. Actualmente solo se admite pcm (24 kHz, 16 bits, mono) y es el valor predeterminado.

input_audio_transcriptionobject (opcional)

Configuración de transcripción de audio de entrada. Aplica a qwen-audio-3.1-realtime-plus.

Propiedades

languagestring (opcional)

El idioma de origen del audio de entrada.

Valores válidos:

zh: Chino
en: Inglés
ja: Japonés
ko: Coreano
vi: Vietnamita
th: Tailandés
id: Indonesio
ms: Malayo
tl: Filipino
hi: Hindi
ar: Árabe
fr: Francés
de: Alemán
es: Español
pt: Portugués
ru: Ruso
it: Italiano
nl: Neerlandés
sv: Sueco
da: Danés
fi: Finés
no: Noruego
el: Griego
pl: Polaco
cs: Checo
hu: Húngaro
ro: Rumano
bg: Búlgaro
hr: Croata
sk: Eslovaco

output_audioobject (opcional)

Configuración de audio de salida. Aplica a qwen-audio-3.1-realtime-plus.

Propiedades

languagestring (opcional)

El idioma de destino del audio de salida.

Este parámetro aplica a la síntesis de voz (TTS). El modelo hace todo lo posible por producir habla en el idioma objetivo, pero esto no está garantizado, y el idioma del texto de respuesta no cambia. Para generar texto en el idioma objetivo, indique el requisito explícitamente en el prompt, por ejemplo, especificando el idioma de respuesta en instructions.

Valores válidos:

zh: Chino
en: Inglés
fr: Francés
de: Alemán
ja: Japonés
ko: Coreano
ru: Ruso
pt: Portugués
th: Tailandés
id: Indonesio
vi: Vietnamita
es: Español
it: Italiano
ms: Malayo
fil: Filipino
ar: Árabe

max_history_turnsinteger (opcional)

Número máximo de turnos de conversación (pares pregunta-respuesta) incluidos en una sola solicitud. Valores válidos: de 1 a 50. Valor predeterminado: 20.

enable_searchboolean (opcional)

Aplica a los modelos qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus y qwen-audio-3.0-realtime-flash.

Especifica si se debe habilitar la búsqueda web. Valor predeterminado: false. Cuando está habilitada, el modelo decide si buscar en la web basándose en la consulta en tiempo real.

tools y enable_search no pueden habilitarse al mismo tiempo.

search_optionsobject (opcional)

La configuración de búsqueda web. Este parámetro solo surte efecto cuando enable_search se establece en true.

Propiedades

enable_sourceboolean (opcional)

Especifica si se deben devolver las fuentes de los resultados de búsqueda. Establezca este parámetro en true para devolver las fuentes.

toolsarray (opcional)

Definiciones de herramientas para Function Calling. Una vez configuradas, el modelo decide si llamar a una herramienta basándose en la entrada del usuario.

Propiedades

typestring(obligatorio)

Valor fijo: function.

function.namestring(obligatorio)

Nombre de la función de herramienta.

function.descriptionstring (opcional)

Descripción de la función de herramienta. El modelo utiliza esto para determinar si debe llamar a la herramienta.

function.parametersobject (opcional)

Descripción de los parámetros de entrada de la función de herramienta. El modelo utiliza esto para extraer los parámetros requeridos. Omita este campo si la función no toma parámetros.

Propiedades

typestring(obligatorio)

Valor fijo: object.

propertiesobject (opcional)

Describe el nombre, el tipo de datos y la descripción de cada parámetro.

requiredarray (opcional)

Especifica qué parámetros son obligatorios.

turn_detectionobject|null (opcional)

Configuración de detección de turnos. Para cambiar al modo push-to-talk, establezca este campo en null. En el modo push-to-talk, el audio debe confirmarse manualmente y la inferencia debe activarse manualmente. Si no se proporciona este campo, VAD se habilita con sus parámetros predeterminados.

Propiedades

typestring (opcional)

Tipo de VAD. Valores válidos:

server_vad (predeterminado): Detecta el inicio y el final del habla basándose en características acústicas y activa automáticamente la inferencia.
smart_turn: Un modo inteligente de detección de turnos que combina percepción acústica y comprensión semántica para determinar los límites de los turnos. Sonidos de relleno como "um" o "eh" no activan un nuevo turno ni interrumpen la reproducción del modelo.

thresholdfloat (opcional)

Sensibilidad de VAD. Solo efectiva en modo server_vad (ignorada en modo smart_turn). Valores más bajos aumentan la sensibilidad de VAD, facilitando la detección de sonidos tenues (incluido el ruido de fondo) como habla. Valores más altos disminuyen la sensibilidad, requiriendo un habla más clara y fuerte para activar la detección.

Rango: [-1.0, 1.0]. Valor predeterminado: 0.5.

silence_duration_msinteger (opcional)

Duración mínima de silencio (en milisegundos) después de que termina el habla antes de activar una respuesta del modelo. Solo efectivo en modo server_vad (ignorado en modo smart_turn). Valores más bajos producen respuestas más rápidas pero pueden causar activaciones false durante pausas breves.

Rango: [200, 6000]. Valor predeterminado: 800. Rango recomendado para conversaciones: 400-800.

voiceprint_audio_urlsarray (opcional)

Solo efectivo en modo smart_turn. Una lista de URL accesibles públicamente que apuntan a muestras de audio pregrabadas del usuario objetivo, utilizadas para la mejora del hablante. Una vez registrado, el modelo se fija en el hablante objetivo durante conversaciones dúplex, ignorando efectivamente otras voces y el ruido de fondo. Máximo 5 URL. Requisitos de formato de audio: PCM de 16kHz o WAV.

ImportanteEste parámetro solo puede configurarse en el primer session.update evento. Se ignora en eventos session.update subsiguientes.

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

Configuración de idioma (qwen-audio-3.1-realtime-plus)

Después de conectarse a qwen-audio-3.1-realtime-plus, puede enviar el siguiente evento session.update para establecer el idioma de origen del audio de entrada en chino y el idioma de destino del audio de salida en inglés.

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

Registro de impresión de voz (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"
            ]
        }
    }
}

input_audio_buffer.append

Descripción: Añade datos de audio al búfer de entrada. Envíe este evento continuamente a alta frecuencia, por ejemplo, un fragmento cada 20–40 ms. El servidor no envía confirmación para este evento.

typestring(obligatorio)

Tipo de evento. Valor fijo: input_audio_buffer.append.

audiostring(obligatorio)

Datos de audio codificados en Base64.

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

input_audio_buffer.commit

Descripción: Solo modo Push-to-talk. Confirma el audio almacenado en el búfer como un mensaje de usuario. Esto no activa automáticamente la inferencia. Envíe response.create para activar la inferencia manualmente.

Este evento se ignora en los modos server_vad y smart_turn.

typestring(obligatorio)

Tipo de evento. Valor fijo: input_audio_buffer.commit.

{
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

Descripción: Solo modo Push-to-talk. Borra el audio no confirmado del búfer. Este evento se ignora en los modos server_vad y smart_turn. El servidor responde con un evento input_audio_buffer.cleared.

typestring(obligatorio)

Tipo de evento. Valor fijo: input_audio_buffer.clear.

{
    "type": "input_audio_buffer.clear"
}

conversation.item.create

Descripción: Inserta un elemento de conversación en el contexto de conversación. Utilice este evento para inyectar contexto histórico o agregar contenido de texto, o para devolver resultados de Function Calling.

NotaSi item.id ya existe en la conversación, se devuelve un error y el elemento no se crea.

typestring(obligatorio)

Tipo de evento. Valor fijo: conversation.item.create.

previous_item_idstring (opcional)

Especifica el elemento de conversación después del cual se inserta el nuevo elemento. Si no se proporciona, el elemento se añade al final de la conversación.

itemobject(obligatorio)

El elemento de conversación a crear.

Propiedades

idstring (opcional)

Identificador único para el elemento de conversación. Si no se proporciona, el servidor genera uno automáticamente. Se devuelve un error si el ID especificado ya existe en la conversación.

typestring(obligatorio)

Tipo de elemento de conversación. Valores válidos:

message: Un mensaje de conversación regular.
function_call: Una solicitud de llamada de función. Generalmente generada por el servidor, pero los clientes también pueden usarla para inyectar contexto histórico.
function_call_output: Un resultado de ejecución de herramienta. Después de recibir un function_call, el cliente ejecuta la herramienta y devuelve el resultado utilizando este tipo.

rolestring (obligatorio para el tipo message)

Rol del mensaje. Valores válidos: system, user, assistant.

contentarray (obligatorio para el tipo message)

Lista de elementos de contenido del mensaje. Cada elemento contiene un campo type y los campos de datos correspondientes.

Tipos de contenido admitidos por rol

system

input_text: Mensaje del sistema. Campo obligatorio: text.

user

input_text: Entrada de texto del usuario. Campo obligatorio: text.
input_audio: Entrada de audio del usuario. Campo obligatorio: audio (codificado en Base64).

assistant

output_text: Salida de texto del asistente. Campo obligatorio: text.

call_idstring (obligatorio para los tipos function_call / function_call_output)

Identificador único para la llamada de función, utilizado para correlacionar solicitudes y resultados.

namestring (obligatorio para el tipo function_call)

Nombre de la función a llamar.

argumentsstring (obligatorio para el tipo function_call)

Parámetros de llamada de función en formato de cadena JSON.

outputstring (obligatorio para el tipo function_call_output)

Resultado de ejecución de herramienta en formato de cadena JSON.

Inyectar un mensaje de texto de usuario:

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

Devolver un resultado de Function Calling:

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

conversation.item.retrieve

Descripción: Recupera un elemento de conversación almacenado en el servidor. El contenido de tipo audio en la respuesta contiene solo la transcripción (transcript), no los datos de audio originales.

typestring(obligatorio)

Tipo de evento. Valor fijo: conversation.item.retrieve.

item_idstring(obligatorio)

ID del elemento de conversación a recuperar. El servidor devuelve el resultado en un evento conversation.item.retrieved.

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

conversation.item.delete

Descripción: Elimina un elemento de conversación del contexto de conversación. El servidor confirma la eliminación con un evento conversation.item.deleted.

typestring(obligatorio)

Tipo de evento. Valor fijo: conversation.item.delete.

item_idstring(obligatorio)

ID del elemento de conversación a eliminar.

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

response.create

Descripción: Activa la inferencia del modelo. El comportamiento varía según el modo:

Modo Push-to-talk: Debe llamarse manualmente. Confirme primero el audio almacenado en el búfer con input_audio_buffer.commit, o devuelva un resultado function_call_output antes de activarlo. No puede llamarse mientras se está generando una respuesta.
Modo server_vad: Normalmente activado automáticamente por el servidor. Los clientes también pueden llamarlo manualmente cuando no se está generando ninguna respuesta. No puede llamarse mientras se está generando una respuesta.
Modo smart_turn: Puede llamarse mientras se espera el siguiente turno del usuario. No puede llamarse durante un turno activo (entre input_audio_buffer.speech_started y response.done).

El campo opcional response reemplaza los valores predeterminados de la sesión para la ronda de inferencia actual. En escenarios de Function Calling, después de que el cliente devuelve un function_call_output, este evento activa la segunda ronda de inferencia.

NotaEn los modos server_vad y smart_turn, las inferencias activadas manualmente aún pueden ser interrumpidas por nuevo habla.

typestring(obligatorio)

Tipo de evento. Valor fijo: response.create.

responseobject (opcional)

Reemplaza los valores predeterminados de la sesión para la ronda de inferencia actual. Si no se proporciona, se utiliza la configuración de sesión actual.

Propiedades

modalitiesarray (opcional)

Reemplaza las modalidades de salida para la ronda actual. Los valores válidos son los mismos que session.update modalities.

voicestring (opcional)

Reemplaza la voz de TTS para la ronda actual.

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

response.cancel

Descripción: Cancela la inferencia actual. Cualquier texto generado hasta el momento se guarda en la lista de elementos. Luego, el servidor devuelve un evento response.done con status=cancelled.

Se devuelve un error si no hay ninguna inferencia en curso.

typestring(obligatorio)

Tipo de evento. Valor fijo: response.cancel.

{
    "type": "response.cancel"
}