Qwen-Audio-Realtime Android 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 enable the active audio data push mode. Default: "false".
When set to "true" to enable the active audio data push mode, and the SDK version supports on-device audio capabilities (such as AEC and VAD), the on-device audio capabilities are enabled by default.

workspace

String

No

When audio_update_manually is set to "true" and an on-device audio capability (such as AEC or VAD) is enabled, you must set workspace, which is the path where on-device resource files are stored.

debug_path

String

No

The storage path of log files. This parameter takes effect only when save_log is set to true when calling the initialize method. In this case, you must set the log file path, otherwise an error is returned. The SDK retains at most two log files locally.

save_wav

String

No

Whether to save audio files for debugging. The audio files are saved under debug_path.
Default: "false".
Valid values:

• "true": yes
• "false": no

max_log_file_size

int

No

The maximum size of log files in bytes.
This parameter takes effect only when save_log is set to true when calling the initialize method.
Default: 104857600 (100 * 1024 * 1024 bytes, i.e. 100 MiB).

log_track_level

int

No

The filter level that controls the log content sent through the log callback (onNuiLogTrackCallback).
Default: 2.
Valid values:

• 0: LOG_LEVEL_VERBOSE
• 1: LOG_LEVEL_DEBUG
• 2: LOG_LEVEL_INFO
• 3: LOG_LEVEL_WARNING
• 4: LOG_LEVEL_ERROR
• 5: LOG_LEVEL_NONE (disables this feature)

aec_params

object

No

Advanced configuration object for the on-device AEC capability. This configuration object is enabled only when audio_update_manually is set to "true".

aec_params.enable_aec

boolean

No

Whether to enable the on-device AEC echo cancellation capability.
When audio_update_manually is set to "true" and the SDK version supports the on-device AEC audio capability, it is enabled by default.

aec_params.save_audio

boolean

No

Whether to enable the audio storage feature of the on-device AEC echo cancellation module. When save_wav is "true" and debug_path is set, it is enabled by default, and the AEC runtime audio data is stored under debug_path.

aec_params.enable_aec_data_callback

boolean

No

Whether to send the AEC-processed data to the user. Default: false. After it is enabled, the data is received in EVENT_AEC_DATA of onNuiAssistEventCallback.

vad_params

object

No

Advanced configuration object for the on-device VAD capability.
This configuration object is enabled only when audio_update_manually is set to "true".

vad_params.enable_vad

boolean

No

Whether to enable the on-device VAD human voice detection capability.
When audio_update_manually is set to "true" and the SDK version supports the on-device VAD audio capability, it is enabled by default.

vad_params.save_audio

boolean

No

Whether to enable the audio storage feature of the on-device VAD human voice detection module.
When save_wav is "true" and debug_path is set, it is enabled by default, and the VAD runtime audio data is stored under debug_path.

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.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, and qwen-audio-3.0-realtime-flash model series.

nls_config.sr_format

string

Yes

Input audio format. Currently only pcm (16kHz 16bit mono) is supported, which is the default.

nls_config.modalities

string

No

A string in array format. The output modality settings of the model. Valid values:

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

nls_config.voice

string

No

TTS voice name. The default is longanqian_v3.1 for 3.1 Plus/Flash and longanqian for 3.0 Plus/Flash. This parameter can be set only in the first session.update; values passed in later are ignored.

• System voices for 3.1 Plus/Flash: valid values include longanqian_v3.1 and all voices in the voice lists for 3.1 TTS Plus/Flash. For the complete range, see Voice configuration.
• System voices for 3.0 Plus/Flash: longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
• Cloned voices: Create a voice through the voice cloning API and pass the returned voice_id as this parameter's value. See Voice configuration.

nls_config.enable_speech_emotion

boolean

No

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

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 in array format. A list of Function Calling tool definitions. After this parameter is configured, the model can decide whether to call a tool based on the user input.
Parameter description:
typestring(required)
Fixed to function.
function.namestring(required)
The name of the tool function.
function.descriptionstring(optional)
A description of the tool function. The model uses this description to decide whether to call the tool.
function.parametersobject(optional)
A description of the tool function parameters. The model uses this description to extract the required parameters. If the function takes no parameters, you can omit this field.
Example:

[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询指定城市的天气信息。",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "城市"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  }
]

nls_config.turn_detection

string

No

The turn detection fields described below apply to qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, and qwen-audio-3.0-realtime-flash.

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. Valid values:

• server_vad (default): detects the start and end of speech based on acoustic features and automatically triggers inference.
• smart_turn: intelligent turn detection that combines acoustic perception and semantic understanding, determining turn boundaries through both acoustic and semantic judgment. Sounds without semantic content (such as "um" and "ah") do not trigger a conversation turn or interrupt model playback.
• smart_turn_v2 (recommended): enhances conversation context understanding based on smart_turn to better identify interaction intent in multi-speaker scenarios. It reduces false responses and false interruptions caused by bystanders speaking or irrelevant interjections.

nls_config.turn_detection.threshold

float

No

VAD sensitivity. Applies to server_vad, smart_turn, and smart_turn_v2. The lower the value, the more easily faint sounds (including background noise) are recognized as speech; the higher the value, the clearer and louder the speech required to trigger detection.
Valid range: [-1.0, 1.0]. Default: 0.5.

nls_config.turn_detection.silence_duration_ms

int

No

The minimum silence duration after speech ends, in milliseconds, effective only in server_vad mode (no effect in smart_turn and smart_turn_v2 modes). The model response is triggered when the silence reaches this duration. The lower the value, the faster the response, but brief pauses may also be falsely triggered.
Valid range: [200, 6000]. Default: 800. 400-800 is recommended for conversation scenarios.

nls_config.turn_detection.voiceprint_audio_urls

string

No

A string in array format. Effective in smart_turn and smart_turn_v2 modes. A list of publicly accessible URLs of prerecorded audio for the target user, used for speaker enhancement. The model uses these audio files to lock onto the target speaker in duplex conversations, ignoring other speakers' voices and background noise. Up to 5 URLs are supported. Audio format requirements: 16kHz PCM or WAV.

callback

INativeNuiCallback

The implementation of the event and data callback interface.

parameters

String

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

level

Constants.LogLevel

Controls the print level of the SDK's own logs.

save_log

boolean

Whether to save local logs. If set to true, you must specify the path through debug_path in the connection and control parameters, and you can set the file size through max_log_file_size.

params

String

Voice conversation parameters.

vad_mode

VadMode

VAD mode. Fixed to VadMode.TYPE_P2T.

dialog_params

String

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

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

params

String

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

params.type

String

Fixed to "action".

params.command

String

The specific runtime command. Currently supports function_call, play_start, and play_over.

• function_call: the command for updating a function call request.
• play_start: when on-device AEC is used, this command notifies the SDK's internal AEC player to start playing audio.
• play_over: when on-device AEC is used, this command notifies the SDK's internal AEC player that playback has ended.

params.context

String

Updates the function call request when command is "function_call".

params.context.type

String

Event type. This parameter must be set when command is "function_call".

• conversation.item.create: manually inserts a conversation item into the conversation context. This can be used to inject historical context, supplement text information, or write back the tool execution result of a Function Calling.
• response.create: after the conversation.item.create command is sent, this command triggers a second round of inference.

params.context.item

object

Required when params.context.type is conversation.item.create. Represents the conversation item to create. See the details below.

params.context.response

object

Can be set when params.context.type is response.create. Represents the session default configuration used to override the inference of this round. If not passed, the current session configuration is used. See the details below.

id

String

Optional. The unique identifier of the conversation item. If not passed, the server generates it automatically. If the specified ID already exists in the conversation, an error is returned.

type

String

Required. The conversation item type. Valid values:

• message: a regular conversation message.
• function_call: a function call request. Usually generated by the server; the client can also use it to supplement historical context.
• function_call_output: a tool execution result. After receiving a function_call, the client executes the tool and uses this type to write back the result.

role

String

Required for the message type. The message role. Valid values: system, user, and assistant.

content

array

Required for the message type. A list of message content. Each element contains a type and the corresponding data field.
Content types supported by each role:
system
input_text: a system message. The required field is text.
user

• input_text: user text input. The required field is text.
• input_audio: user audio input. The required field is audio (Base64-encoded).

call_id

String

(Required for the function_call and function_call_output types)
The unique identifier of the function call, used to associate the request and the result.

name

String

(Required for the function_call type)
The name of the function to call.

arguments

String

(Required for the function_call type)
The function call parameters, in JSON string format.

output

String

(Required for the function_call_output type)
The tool execution result, in JSON string format.

modalities

array

A string in array format. The output modality settings of the model. Valid values:

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

voice

string

Overrides the TTS voice for this round.

data

byte[]

The audio data to push.

len

int

The number of bytes of the pushed audio data.

first_pack

boolean

Please ignore this parameter. You do not need to pay attention to it.

data

byte[]

The audio data to push.

len

int

The number of bytes of the pushed audio data.

first_pack

boolean

Please ignore this parameter. You do not need to pay attention to it.

event

NuiEvent

The callback event.

resultCode

int

Valid only when the EVENT_ASR_ERROR event occurs.

arg2

int

A reserved parameter.

asrResult

AsrResult

The speech recognition result.

kwsResult

KwsResult

The voice wake-up feature. You do not need to pay attention to this parameter.

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 completely close the recording device.

buffer

byte[]

The audio data to fill.

len

int

The number of bytes of the filled audio data.

event

int

A NuiEvent event

info

String

You do not need to pay attention to this parameter.

info_len

int

You do not need to pay attention to this parameter.

data

byte[]

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

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 subtitle event in audio mode. Subtitle segments are returned in streaming mode.

EVENT_AUDIO_TRANSCRIPTION_COMPLETED

A subtitle output completion event in audio mode.

EVENT_OTHER_RESULT

Other uncategorized event information, such as function_call results.

EVENT_ASR_TTS_START

The AI starts returning TTS data.

EVENT_ASR_TTS_DATA

The TTS data returned by the AI.

EVENT_ASR_TTS_COMPLETE

The AI has finished returning TTS data.

EVENT_AEC_DATA

The audio data after AEC echo cancellation.