Alibaba Cloud Model Studio:SDK de iOS para conversación de voz en tiempo real de Qwen-Audio-3.0-Realtime

url

String

Sí

Endpoint del servicio:

• wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
• China (Pekín): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
• Singapur: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

apikey

String

Sí

Clave de API.

service_mode

String

Sí

Modo de ejecución. Establezca este parámetro en "1" para conversaciones de voz en tiempo real.

device_id

String

Sí

Una cadena única que identifica al usuario final. Puede utilizar un ID de usuario dentro de la aplicación o un identificador de dispositivo generado por el cliente. Este ID se utiliza principalmente para el rastreo de registros y la solución de problemas.

audio_update_manually

String

No

Indica si se deben enviar activamente datos de audio. Valor predeterminado: "false". Si se establece en "true" y el SDK admite capacidades de audio en el dispositivo, como AEC y VAD, dichas capacidades se habilitan de forma predeterminada.

workspace

String

No

La ruta de almacenamiento para los archivos de recursos en el dispositivo. Este parámetro es obligatorio cuando audio_update_manually es "true" y está habilitada una capacidad de audio en el dispositivo, como AEC o VAD.

debug_path

String

No

La ruta de almacenamiento del archivo de registro. Este parámetro solo surte efecto cuando save_log es true en nui_initialize. En este caso, la ruta es obligatoria. El SDK conserva como máximo dos archivos de registro localmente.

save_wav

String

No

Indica si se debe guardar el audio de depuración en debug_path. Valor predeterminado: "false". Los valores válidos son "true" y "false". Este parámetro solo surte efecto cuando save_log es true, y debug_path también debe estar definido.

max_log_file_size

int

No

El tamaño máximo del archivo de registro en bytes. Este parámetro solo surte efecto cuando save_log es true. Predeterminado: 104857600 (100 × 1024 × 1024 bytes, o 100 MiB).

log_track_level

int

No

El nivel de filtro para los registros enviados a través de onNuiLogTrackCallback. Valor predeterminado: 2. Valores válidos: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR) y 5 (NONE). Un registro se devuelve solo cuando su nivel es mayor o igual tanto a log_track_level como al level pasado a nui_initialize. Por ejemplo, si log_track_level es 2 (INFO) y level es 3 (WARNING), solo se devuelven registros de nivel WARNING y superior (valores mayores o iguales a 3).

service_type

int

Sí

Tipo de servicio de voz. Establezca este parámetro en 4 para conversaciones de voz en tiempo real.

nls_config

object

Sí

Configuración principal de la conversación de voz, incluida la selección del modelo y el comportamiento de la conversación.

nls_config.model

string

Sí

Nombre del modelo. Admite las series de modelos qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus y qwen-audio-3.0-realtime-flash.

nls_config.sr_format

string

Sí

Formato de audio de entrada. Solo se admite pcm. El formato predeterminado es PCM monoaural de 16 kHz y 16 bits.

nls_config.modalities

string

No

Una cadena que contiene una matriz de modalidades de salida. Valores válidos:

• ["text"]: devuelve solo texto.
• ["audio", "text"] (predeterminado): devuelve tanto audio como texto.

nls_config.voice

string

No

Voz TTS. El valor predeterminado es longanqian_v3.1 para 3.1 Plus y longanqian para 3.0 Plus/Flash. Este parámetro solo se puede establecer en la primera session.update; los valores posteriores se ignoran. Voces del sistema: longanqian, longanlingxin, longanlingxi, longanxiaoxin y longanlufeng. También puede especificar un voice_id clonado creado a través de la API de clonación de voz. Consulte Configuración de voz.

3.1 Plus también admite longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1 y cally_v3.1.

nls_config.enable_speech_emotion

BOOL

No

Indica si se debe habilitar la expresión emocional mejorada. Cuando está habilitada, la voz de respuesta presenta una variación emocional más notable. Valor predeterminado: YES. Valores válidos: YES y NO.

nls_config.instructions

string

No

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

nls_config.max_history_turns

int

No

Número máximo de turnos históricos de preguntas y respuestas permitidos en una solicitud. Valores válidos: de 1 a 50. Predeterminado: 20.

nls_config.tools

string

No

Una cadena que contiene una matriz de definiciones de herramientas de Function Calling. Después de configurar este parámetro, el modelo decide si llamar a una herramienta basándose en la entrada del usuario. Cada definición utiliza type (obligatorio y fijado en function) y un objeto function que contiene name (obligatorio), description (opcional) y parameters (opcional). Si una función no tiene argumentos, omita parameters.
Ejemplo:

[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Queries weather information for a specified city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  }
]

nls_config.turn_detection

string

No

Una cadena que contiene un objeto JSON para la detección de turnos. Si se omite, la sesión utiliza el modo pulsar para hablar, en el cual el audio se confirma y la inferencia se activa manualmente. Si se establece, se habilita el modo de conversación dúplex.

nls_config.turn_detection.type

string

No

Tipo de VAD. server_vad (predeterminado) detecta los límites del habla a partir de características acústicas y activa automáticamente la inferencia. smart_turn combina señales acústicas y semánticas; los sonidos sin contenido semántico, como las muletillas, no inician un turno ni interrumpen la reproducción del modelo.

nls_config.turn_detection.threshold

float

No

Sensibilidad de VAD. Este parámetro solo se aplica a server_vad y no tiene efecto en smart_turn. Los valores más bajos hacen que el VAD sea más sensible a sonidos tenues y ruido de fondo; los valores más altos requieren un habla más clara y fuerte. Rango válido: [-1.0, 1.0]. Valor predeterminado: 0.5.

nls_config.turn_detection.silence_duration_ms

int

No

Duración mínima de silencio después del habla, en milisegundos, antes de que se active la respuesta del modelo. Este parámetro solo se aplica a server_vad y no tiene efecto en smart_turn. Los valores más bajos reducen la latencia, pero pueden activarse con pausas breves. Rango válido: [200, 6000]. Valor predeterminado: 800. Recomendado para conversación: de 400 a 800.

nls_config.turn_detection.voiceprint_audio_urls

string

No

Una cadena que contiene una matriz de URL de audio pregrabado de acceso público para el hablante objetivo. Este parámetro solo se aplica a smart_turn. En conversaciones dúplex, ayuda al modelo a centrarse en el hablante objetivo e ignorar a otros hablantes y el ruido de fondo. Se admiten hasta cinco URL. El audio debe ser PCM o WAV de 16 kHz.

parameters

char*

Una cadena JSON que contiene parámetros de autenticación, conexión y depuración. Consulte Parámetros de conexión y control.

level

NuiSdkLogLevel

Nivel de impresión para los propios registros del SDK.

save_log

BOOL

Si se deben guardar los registros localmente. Si se establece en YES, especifique una ruta con debug_path en Parámetros de conexión y control, y opcionalmente configure el tamaño del archivo con max_log_file_size.

params

char*

Parámetros de conversación de voz.

vad_mode

NuiVadMode

Modo VAD. Fijo en MODE_P2T.

dialog_params

char*

Si apikey en los parámetros de conexión y control es una clave API temporal, actualícela aquí después de que caduque.
Formato JSON:

{
  "apikey": "st-****"
}

force

BOOL

Si se debe finalizar forzosamente y descartar el resultado final.

• YES: Finaliza la tarea inmediatamente sin esperar a que el servidor devuelva el resultado final de la conversación.

• NO: Finaliza la tarea, pero espera a que se devuelva el resultado completo.

params

char*

Una cadena JSON utilizada para actualizar el comportamiento en tiempo de ejecución, como el contexto de la conversación.

params.type

String

Establecido en "action".

params.command

String

Comando de tiempo de ejecución. Valores válidos:

• function_call: actualiza una solicitud de llamada de función.
• play_start: cuando se utiliza AEC en el dispositivo, notifica al SDK que la reproducción de audio ha comenzado.
• play_over: cuando se utiliza AEC en el dispositivo, notifica al SDK que la reproducción de audio ha terminado.

params.context

String

Actualización de solicitud de llamada de función. Se usa cuando command es "function_call".

params.context.type

String

Tipo de evento. Este parámetro es obligatorio cuando command es "function_call". conversation.item.create inserta un elemento de conversación para contexto histórico, texto complementario o resultado de una herramienta. Después de enviar conversation.item.create, utilice response.create para activar otra inferencia.

params.context.item

object

Requerido cuando params.context.type es conversation.item.create. El elemento de conversación a crear.

params.context.response

object

Opcional cuando params.context.type es response.create. Anula los valores predeterminados de la sesión para esta inferencia. Si se omite, se utiliza la configuración actual de la sesión.

id

String

ID de elemento de conversación único opcional. Si se omite, el servidor genera uno. Se devuelve un error si el ID especificado ya existe.

type

String

Tipo de elemento obligatorio. Valores válidos:

• message: un mensaje normal.
• function_call: una solicitud de llamada de función. Este tipo suele ser generado por el servidor. El cliente también puede utilizarlo para agregar contexto histórico.
• function_call_output: resultado de ejecución de una herramienta. Después de recibir un function_call, el cliente ejecuta la herramienta y utiliza este tipo para devolver el resultado.

role

String

Requerido para message. Valores válidos: system, user y assistant.

content

array

Obligatorio para message. Cada elemento contiene un type y el campo de datos asociado. system admite input_text con text; user admite input_text con text y input_audio con audio codificado en Base64; assistant admite output_text con text.

call_id

String

Requerido para function_call y function_call_output. El ID único que asocia una solicitud de llamada de función con su resultado.

name

String

Requerido para function_call. El nombre de la función a llamar.

arguments

String

Requerido para function_call. Argumentos de la función como una cadena JSON.

output

String

Requerido para function_call_output. Resultado de ejecución de la herramienta como una cadena JSON.

modalities

array

Modalidades de salida. ["text"] devuelve solo texto. ["audio", "text"] (predeterminado) devuelve tanto audio como texto.

voice

string

Anula la voz TTS para esta inferencia.

data

const char *

Los datos de audio a enviar.

length

int

La longitud de los datos de audio, en bytes.

first_pack

BOOL

No necesita utilizar este parámetro.

data

const char *

Los datos de audio a enviar.

length

int

La longitud de los datos de audio, en bytes.

first_pack

BOOL

No necesita utilizar este parámetro.

nuiEvent

NuiCallbackEvent

Evento de callback.

dialog

long

ID de sesión. No necesita utilizar este parámetro.

wuw

char*

Activación por voz. No necesita utilizar este parámetro.

asr_result

char*

Resultado del reconocimiento de voz.

finish

BOOL

Si la ronda de reconocimiento actual ha finalizado.

code

int

Válido solo cuando ocurre el evento EVENT_ASR_ERROR.

STATE_OPEN

La interacción ha comenzado. Puede abrir el dispositivo de grabación e iniciar la grabación.

STATE_PAUSE

La interacción se ha detenido. Puede detener la grabación.

STATE_CLOSE

La instancia del SDK ha sido liberada. Puede cerrar el dispositivo de grabación por completo.

audioData

char *

Los datos de audio a suministrar.

len

int

El tamaño de los datos de audio suministrados, en bytes.

nuiEvent

NuiCallbackEvent

El evento de devolución de llamada.

info

char *

No necesita utilizar este parámetro.

info_len

int

No necesita utilizar este parámetro.

buffer

char *

Datos auxiliares, como el audio TTS devuelto por el modelo.

len

int

La longitud de los datos auxiliares, en bytes.

EVENT_TRANSCRIBER_STARTED

La tarea se inició correctamente.

EVENT_VAD_START

Se activa inmediatamente después de que comienza la tarea. Esto no significa que se haya detectado el inicio del habla.

EVENT_VAD_END

Se detectó el final del habla.

EVENT_ASR_PARTIAL_RESULT

Un resultado intermedio del reconocimiento de voz.

EVENT_ASR_ERROR

Ocurrió un error durante la conversación de voz.

EVENT_MIC_ERROR

Se activa cuando no se reciben datos de audio durante dos segundos consecutivos.

EVENT_SENTENCE_END

Se detectó el final de una oración y se devolvió un resultado de reconocimiento completo.

EVENT_TRANSCRIBER_COMPLETE

La conversación de voz finalizó.

EVENT_AUDIO_TRANSCRIPTION

Un evento de transcripción de texto incremental para la salida de audio. Los segmentos de transcripción se devuelven en modo streaming.

EVENT_AUDIO_TRANSCRIPTION_COMPLETED

La transcripción de la salida de audio está completa.

EVENT_OTHER_RESULT

Otra información de eventos, como un resultado de Function Calling.

EVENT_ASR_TTS_START

El modelo comenzó a devolver audio TTS.

EVENT_ASR_TTS_DATA

Audio TTS devuelto por el modelo.

EVENT_ASR_TTS_COMPLETE

El modelo terminó de devolver audio TTS.

EVENT_AEC_DATA

Datos de audio procesados por AEC.