Alibaba Cloud Model Studio:Qwen-Audio-3.0-Realtime real-time voice conversation iOS SDK

url

String

Yes

Service endpoint:

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

apikey

String

Yes

API key.

service_mode

String

Yes

Runtime mode. Set this parameter to "1" for real-time voice conversation.

device_id

String

Yes

A unique string that identifies the end user. You can use an in-app user ID or a client-generated device identifier. This ID is mainly used for log tracing and troubleshooting.

audio_update_manually

String

No

Whether to actively push audio data. Default: "false". If set to "true" and the SDK supports on-device audio capabilities such as AEC and VAD, those capabilities are enabled by default.

workspace

String

No

The storage path for on-device resource files. This parameter is required when audio_update_manually is "true" and an on-device audio capability such as AEC or VAD is enabled.

debug_path

String

No

The log file storage path. This parameter takes effect only when save_log is true in nui_initialize. In this case, the path is required. The SDK retains at most two log files locally.

save_wav

String

No

Whether to save debug audio under debug_path. Default: "false". Valid values are "true" and "false". This parameter takes effect only when save_log is true, and debug_path must also be set.

max_log_file_size

int

No

The maximum log file size in bytes. This parameter takes effect only when save_log is true. Default: 104857600 (100 × 1024 × 1024 bytes, or 100 MiB).

log_track_level

int

No

The filter level for logs sent through onNuiLogTrackCallback. Default: 2. Valid values: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR), and 5 (NONE). A log is returned only when its level is greater than or equal to both log_track_level and the level passed to nui_initialize. For example, if log_track_level is 2 (INFO) and level is 3 (WARNING), only WARNING and higher-level logs (values greater than or equal to 3) are returned.

service_type

int

Yes

Voice service type. Set this parameter to 4 for real-time voice conversation.

nls_config

object

Yes

Core voice conversation configuration, including model selection and conversation behavior.

nls_config.model

string

Yes

Model name. Supports the qwen-audio-3.0-realtime-plus and qwen-audio-3.0-realtime-flash model series.

nls_config.sr_format

string

Yes

Input audio format. Only pcm is supported. The default format is 16 kHz, 16-bit, mono PCM.

nls_config.modalities

string

No

A string containing an array of output modalities. Valid values:

• ["text"]: returns text only.
• ["audio", "text"] (default): returns both audio and text.

nls_config.voice

string

No

TTS voice. Default: longanqian. This parameter can be set only in the first session.update; later values are ignored. System voices: longanqian, longanlingxin, longanlingxi, longanxiaoxin, and longanlufeng. You can also specify a cloned voice_id created through the voice cloning API. See Voice configuration.

nls_config.enable_speech_emotion

BOOL

No

Whether to enable enhanced emotional expression. When enabled, the response voice has more noticeable emotional variation. Default: YES. Valid values: YES and NO.

nls_config.instructions

string

No

System instructions that define the model's role, response style, and behavioral preferences for the entire session.

nls_config.max_history_turns

int

No

Maximum number of historical question-answer turns allowed in a request. Valid values: 1 to 50. Default: 20.

nls_config.tools

string

No

A string containing an array of Function Calling tool definitions. After you configure this parameter, the model decides whether to call a tool based on the user input. Each definition uses type (required and fixed to function) and a function object containing name (required), description (optional), and parameters (optional). If a function has no arguments, omit parameters.
Example:

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

A string containing a JSON object for turn detection. If omitted, the session uses push-to-talk mode, in which audio is committed and inference is triggered manually. If set, duplex conversation mode is enabled.

nls_config.turn_detection.type

string

No

VAD type. server_vad (default) detects speech boundaries from acoustic features and automatically triggers inference. smart_turn combines acoustic and semantic signals; sounds without semantic content, such as filler sounds, do not start a turn or interrupt model playback.

nls_config.turn_detection.threshold

float

No

VAD sensitivity. This parameter applies only to server_vad and has no effect on smart_turn. Lower values make VAD more sensitive to quiet sounds and background noise; higher values require clearer and louder speech. Valid range: [-1.0, 1.0]. Default: 0.5.

nls_config.turn_detection.silence_duration_ms

int

No

Minimum silence duration after speech, in milliseconds, before the model response is triggered. This parameter applies only to server_vad and has no effect on smart_turn. Lower values reduce latency but can trigger on brief pauses. Valid range: [200, 6000]. Default: 800. Recommended for conversation: 400 to 800.

nls_config.turn_detection.voiceprint_audio_urls

string

No

A string containing an array of publicly accessible prerecorded audio URLs for the target speaker. This parameter applies only to smart_turn. In duplex conversations, it helps the model focus on the target speaker and ignore other speakers and background noise. Up to five URLs are supported. Audio must be 16 kHz PCM or WAV.

parameters

char*

A JSON string that contains authentication, connection, and debugging parameters. See Connection and control parameters.

level

NuiSdkLogLevel

Print level for the SDK's own logs.

save_log

BOOL

Whether to save logs locally. If set to YES, specify a path with debug_path in Connection and control parameters, and optionally set the file size with max_log_file_size.

params

char*

Voice conversation parameters.

vad_mode

NuiVadMode

VAD mode. Fixed to MODE_P2T.

dialog_params

char*

If apikey in the connection and control parameters is a temporary API key, update it here after it expires.
JSON format:

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

force

BOOL

Whether to end forcibly and discard the final result.

• YES: End the task immediately without waiting for the server to return the final conversation result.

• NO: End the task, but wait for the complete result to return.

params

char*

A JSON string used to update runtime behavior such as the conversation context.

params.type

String

Set to "action".

params.command

String

Runtime command. Valid values:

• function_call: updates a function call request.
• play_start: when on-device AEC is used, notifies the SDK that audio playback has started.
• play_over: when on-device AEC is used, notifies the SDK that audio playback has ended.

params.context

String

Function call request update. Used when command is "function_call".

params.context.type

String

Event type. This parameter is required when command is "function_call". conversation.item.create inserts a conversation item for historical context, supplemental text, or a tool result. After sending conversation.item.create, use response.create to trigger another inference.

params.context.item

object

Required when params.context.type is conversation.item.create. The conversation item to create.

params.context.response

object

Optional when params.context.type is response.create. Overrides the session defaults for this inference. If omitted, the current session configuration is used.

id

String

Optional unique conversation item ID. If omitted, the server generates one. An error is returned if the specified ID already exists.

type

String

Required item type. Valid values:

• message: a regular message.
• function_call: a function call request. This type is typically generated by the server. The client can also use it to add historical context.
• function_call_output: a tool execution result. After receiving a function_call, the client runs the tool and uses this type to write back the result.

role

String

Required for message. Valid values: system, user, and assistant.

content

array

Required for message. Each item contains a type and the associated data field. system supports input_text with text; user supports input_text with text and input_audio with Base64-encoded audio; assistant supports output_text with text.

call_id

String

Required for function_call and function_call_output. The unique ID that associates a function call request with its result.

name

String

Required for function_call. The name of the function to call.

arguments

String

Required for function_call. Function arguments as a JSON string.

output

String

Required for function_call_output. Tool execution result as a JSON string.

modalities

array

Output modalities. ["text"] returns text only. ["audio", "text"] (default) returns both audio and text.

voice

string

Overrides the TTS voice for this inference.

data

const char *

The audio data to push.

length

int

The length of the audio data, in bytes.

first_pack

BOOL

You do not need to use this parameter.

data

const char *

The audio data to push.

length

int

The length of the audio data, in bytes.

first_pack

BOOL

You do not need to use this parameter.

nuiEvent

NuiCallbackEvent

Callback event.

dialog

long

Session ID. You do not need to use this parameter.

wuw

char*

Voice wake-up. You do not need to use this parameter.

asr_result

char*

Speech recognition result.

finish

BOOL

Whether the current recognition round has finished.

code

int

Error code. Valid when the EVENT_ASR_ERROR event occurs. See Error code reference.

STATE_OPEN

The interaction has started. You can open the recording device and start recording.

STATE_PAUSE

The interaction has stopped. You can stop recording.

STATE_CLOSE

The SDK instance has been released. You can close the recording device completely.

audioData

char *

The audio data to supply.

len

int

The size of the supplied audio data, in bytes.

nuiEvent

NuiCallbackEvent

The callback event.

info

char *

You do not need to use this parameter.

info_len

int

You do not need to use this parameter.

buffer

char *

Auxiliary data, such as TTS audio returned by the model.

len

int

The length of the auxiliary data, in bytes.

EVENT_TRANSCRIBER_STARTED

The task started successfully.

EVENT_VAD_START

Triggered immediately after the task starts. This does not mean that the start of speech has been detected.

EVENT_VAD_END

The end of speech was detected.

EVENT_ASR_PARTIAL_RESULT

An intermediate speech recognition result.

EVENT_ASR_ERROR

An error occurred during the voice conversation.

EVENT_MIC_ERROR

Triggered when no audio data is received for two consecutive seconds.

EVENT_SENTENCE_END

The end of a sentence was detected and a complete recognition result was returned.

EVENT_TRANSCRIBER_COMPLETE

The voice conversation ended.

EVENT_AUDIO_TRANSCRIPTION

An incremental text transcript event for audio output. Transcript segments are returned in streaming mode.

EVENT_AUDIO_TRANSCRIPTION_COMPLETED

The transcript for audio output is complete.

EVENT_OTHER_RESULT

Other event information, such as a Function Calling result.

EVENT_ASR_TTS_START

The model started returning TTS audio.

EVENT_ASR_TTS_DATA

TTS audio returned by the model.

EVENT_ASR_TTS_COMPLETE

The model finished returning TTS audio.

EVENT_AEC_DATA

Audio data processed by AEC.