Qwen-Audio-3.0-Realtime实时语音对话iOS SDK

用户指南：关于模型介绍和选型建议请参见实时语音对话。

快速开始

获取 API Key：获取与配置 API Key
下载 SDK 并运行示例代码：
- 下载最新 SDK 整合包。
- 解压 ZIP 包，将其中的 nuisdk.xcframework 添加到工程。
- 在 Build Phases → Link Binary With Libraries 中添加 nuisdk.xcframework。
- 在 General → Frameworks, Libraries, and Embedded Content 中将 nuisdk.xcframework 设置为 Embed & Sign。
- 用 Xcode 打开示例工程。示例代码位于DashQwenAudioChatViewController.m，替换 API Key 后体验功能。

调用步骤

初始化 SDK
按业务需求设置参数：通过nui_initialize接口设置连接与控制参数；通过nui_set_params接口设置语音对话效果参数。
调用nui_dialog_start启动对话流程。
在onNuiAudioStateChanged回调中，根据音频状态开启录音设备。
在onNuiNeedAudioData回调中持续提供录音数据，或者通过nui_update_audio_data持续推送录音数据。
在onNuiAssistEventCallback回调中持续获得 AI 返回的语音数据。
在onNuiEventCallback回调中监听事件并获取事件信息。
调用nui_dialog_cancel停止对话，并通过监听EVENT_TRANSCRIBER_COMPLETE事件确认对话已结束。
当对话功能不再使用时，调用nui_release接口释放 SDK 资源。

请求参数

连接与控制参数

通过在nui_initialize接口的parameters参数中传入一个 JSON 字符串来配置。 参数示例：以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

参数说明

参数	类型	是否必须	说明
`url`	`String`	是	服务地址： `wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 华北2（北京）：`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 新加坡：`wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 调用时，请将 `{WorkspaceId}` 替换为真实的Workspace ID。
`apikey`	`String`	是	API Key。
`service_mode`	`String`	是	运行模式。实时语音对话固定为 `"1"`。
`device_id`	`String`	是	用于标识终端用户的唯一字符串，可设为应用内用户 ID或客户端生成的设备唯一标识符。此 ID主要用于日志追踪和问题排查。
`audio_update_manually`	`String`	否	是否启用主动推送音频数据模式，默认值："false"。当设置为"true"启用主动推送音频数据模式时，且SDK版本支持端侧音频能力（如AEC、VAD），则默认开启端侧音频能力。
`workspace`	`String`	否	端侧资源文件的存储路径。当 `audio_update_manually` 设为 `"true"` 且启用端侧音频能力（如 AEC、VAD）时，必须设置此参数。
`debug_path`	`String`	否	日志文件的存储路径。此参数仅在调用nui_initialize接口时将`save_log`设为`YES`时生效。此时必须设置日志文件路径，否则将报错。本地最多保留两个日志文件。
`save_wav`	`String`	否	是否保存调试用的音频文件。音频文件保存于`debug_path`下。默认值："false"。取值范围： "true"：是 "false"：否此参数仅在调用nui_initialize接口时将`save_log`设为true时生效。同时，`debug_path`也必须被设置。
`max_log_file_size`	`int`	否	设定日志文件的最大字节数。此参数仅在调用nui_initialize接口时将`save_log`设为`YES`时生效。默认值：104857600（100 × 1024 × 1024 字节, 即 100MiB）。
`log_track_level`	`int`	否	控制通过日志回调（onNuiLogTrackCallback）对外发送的日志内容的过滤级别。默认值：2。取值范围： 0：LOG_LEVEL_VERBOSE 1：LOG_LEVEL_DEBUG 2：LOG_LEVEL_INFO 3：LOG_LEVEL_WARNING 4：LOG_LEVEL_ERROR 5：LOG_LEVEL_NONE（表示关闭此功能）注意：`log_track_level`与`level`（通过nui_initialize接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于`log_track_level`和`level`的值，才会被回调。例如，`log_track_level`设为2 (INFO)，`level`设为3 (WARNING)，则只有WARNING及以上级别（数值>=3）的日志才会被回调。

语音对话效果参数

通过在nui_set_params接口的params参数中传入一个 JSON 字符串来配置。 参数示例：以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.1-realtime-plus",
        "sr_format": "pcm"
    }
}

参数说明

一级参数	类型	是否必须	说明
`service_type`	`int`	是	语音服务类型。实时语音对话固定为 `4`。
`nls_config`	`object`	是	语音对话核心配置对象，包含模型选择、对话效果控制等关键参数。
`nls_config.model`	`string`	是	指定模型名。支持qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus和qwen-audio-3.0-realtime-flash系列模型。
`nls_config.sr_format`	`string`	是	输入音频格式。当前仅支持 `pcm`（16kHz 16bit 单声道），为默认值。
`nls_config.modalities`	`string`	否	array 格式的字符串，模型输出模态设置，可选值： `["text"]`：仅输出文本。 `["audio", "text"]`（默认值）：同时输出文本和音频。
nls_config.voice	`string`	否	TTS 音色名称，3.1 Plus 的默认值为 `longanqian_v3.1`，3.0 Plus/Flash 的默认值为 `longanqian`。支持两种类型，仅可在第一次 `session.update` 中设置，后续传入将被忽略。系统音色：可选值：`longanqian`、`longanlingxin`、`longanlingxi`、`longanxiaoxin`、`longanlufeng`。声音复刻音色：通过声音复刻 API 创建，将返回的 `voice_id` 填入此参数。详见音色配置。 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`。
nls_config.enable_speech_emotion	`BOOL`	否	是否开启情绪增强功能。开启后，回复音色的情绪变化更明显。默认值：`YES`。可选值：`YES`、`NO`。
nls_config.instructions	`string`	否	系统指令，用于设定模型的角色身份、回答风格和行为偏好。对整个会话生效。
nls_config.max_history_turns	int	否	允许单次请求的最大历史 QA 轮数。取值范围为 1-50，默认值为 20。
nls_config.tools	`string`	否	array 格式的字符串。Function Calling 工具定义列表。配置后模型可根据用户输入自主决定是否调用工具。内部参数说明： type`string`（必选）固定为 `function`。 function.name`string`（必选）工具函数名称。 function.description`string`（可选）对工具函数功能的描述，模型据此判断是否调用该工具。 function.parameters`object`（可选）对工具函数入参的描述，模型据此提取所需入参。若函数无需入参，可不指定。示例： `[ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的天气信息。", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市" } }, "required": [ "city" ] } } } ]`
nls_config.turn_detection	`string`	否	JSON 对象形式的字符串。轮次检测配置。不设置时则切换为 push-to-talk 模式（手动提交音频并触发推理）。否则启用双工对话模式。
nls_config.turn_detection.type	`string`	否	VAD 类型，可选值： `server_vad`（默认值）：基于声学特征检测语音起止，自动触发推理。 `smart_turn`：融合声学感知与语义理解的智能轮次检测，通过声学与语义双重判断轮次边界。无语义的声音（如”嗯”、”啊”）不会触发对话轮或打断模型播报。
nls_config.turn_detection.threshold	float	否	VAD灵敏度，仅在 server_vad 模式下生效（smart_turn 模式下无效）。值越低，VAD越灵敏，越容易将微弱声音（包括背景噪音）识别为语音；值越高，越不灵敏，需要更清晰、音量更大的语音才能触发。取值范围为[-1.0, 1.0]，默认值为 0.5。
nls_config.turn_detection.silence_duration_ms	`int`	否	语音结束后需保持静音的最短时间（毫秒），仅在 server_vad 模式下生效（smart_turn 模式下无效）。超时即触发模型响应。值越低，响应越快，但可能在短暂停顿时误触发。取值范围为[200, 6000]，默认值为 800。对话场景推荐 400-800。
nls_config.turn_detection.voiceprint_audio_urls	`string`	否	array形式的字符串。仅在 smart_turn 模式下生效。目标用户预录音频的公网可访问 URL 列表，用于说话人增强。传入后，模型将在双工对话中精准锁定目标说话人，有效忽略旁人声音与背景噪声。最多支持 5 个 URL。音频格式要求：16kHz PCM 或 WAV。

关键接口

NeoNui

nui_initialize

初始化语音对话SDK 实例。SDK 为单例模式，在调用 nui_release 前禁止重复初始化。 方法签名

- (NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;

参数说明

参数	类型	说明
`parameters`	`char*`	JSON 字符串，包含鉴权、连接和调试参数。参见连接与控制参数。
`level`	`NuiSdkLogLevel`	控制SDK自身日志的打印级别。
`save_log`	BOOL	是否保存本地日志。若为`YES`，须在连接与控制参数通过`debug_path`指定路径，并可通过`max_log_file_size`设置文件大小。

返回值说明 返回错误码，参见错误码查询。

nui_set_params

以 JSON 格式设置语音对话效果参数。在 nui_dialog_start 之前调用。 方法签名

- (NuiResultCode) nui_set_params:(const char *)params;

参数说明

参数	类型	说明
`params`	`char*`	语音对话效果参数。

返回值说明 返回错误码，参见错误码查询。

nui_dialog_start

开始对话。 方法签名

- (NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;

参数说明

参数	类型	说明
`vad_mode`	`NuiVadMode`	VAD模式。固定为`MODE_P2T`。
`dialog_params`	`char*`	如果连接与控制参数的`apikey`参数使用的是临时API Key，当其过期时，可在此处进行更新。内容为JSON 格式： `{ "apikey": "st-****" }`

返回值说明 返回错误码，参见错误码查询。

nui_dialog_cancel

结束对话或者立即取消当前交互。 方法签名

- (NuiResultCode) nui_dialog_cancel:(BOOL)force;

参数说明

参数	类型	说明
`force`	`BOOL`	是否强制结束而忽略最终结果。 `YES`：不等待服务端返回最终识别结果就立即结束任务。 `NO`：结束任务，但是会等待完整结果返回。

返回值说明 返回错误码，参见错误码查询。

nui_dialog_action

在交互过程中下发对话动作指令，用于更新对话上下文等运行时行为。 方法签名

- (NuiResultCode) nui_dialog_action:(const char *)params;

参数说明

参数	类型	说明
`params`	`char*`	JSON 字符串，用于更新对话上下文等运行时行为。
`params.type`	`String`	固定为 `"action"`。
`params.command`	`String`	具体的运行指令，当前支持 `function_call`、`play_start`、`play_over`。 `function_call`：更新函数调用请求的指令。 `play_start`：当使用端侧AEC时，通过此指令通知SDK内部AEC播放器开始播放音频。 `play_over`：当使用端侧AEC时，通过此指令通知SDK内部AEC播放器已经播放结束。
`params.context`	`String`	当`command`为`"function_call"`时，更新函数调用请求。
`params.context.type`	`String`	事件类型，当`command`为`"function_call"`时必须设置。 `conversation.item.create`：手动向对话上下文插入一条对话项。可用于注入历史上下文、补充文本信息，或写回 Function Calling 的工具执行结果。 `response.create`：在`conversation.item.create`指令发送后，通过此指令触发二轮推理。
`params.context.item`	`object`	`params.context.type`为conversation.item.create时必须设置，表示要创建的对话项。详见如下。
`params.context.response`	`object`	`params.context.type`为response.create时可设置，表示用于覆盖本轮推理的会话默认配置。不传时使用当前会话配置。详见如下。

context.item参数：

参数	类型	说明
id	`String`	可选。对话项的唯一标识符。不传时由服务端自动生成。若指定的 ID 已存在于对话中，会返回错误。
type	`String`	必选。对话项类型，可选值： `message`：普通对话消息。 `function_call`：函数调用请求。通常由服务端生成，客户端也可用于补充历史上下文。 `function_call_output`：工具执行结果。客户端收到 `function_call` 后执行工具，并用该类型写回结果。
role	`String`	`message` 类型必选。消息角色，可选值：`system`、`user`、`assistant`。
content	array	`message` 类型必选。消息内容列表。每个元素包含 `type` 和对应的数据字段。各 role 支持的 content 类型： system `input_text`：系统消息，必填字段 `text`。 user `input_text`：用户文本输入，必填字段 `text`。 `input_audio`：用户音频输入，必填字段 `audio`（Base64 编码）。 assistant `output_text`：助手文本输出，必填字段 `text`。
call_id	`String`	（`function_call` / `function_call_output` 类型必选）函数调用的唯一标识符，用于关联请求和结果。
name	`String`	（`function_call` 类型必选）要调用的函数名称。
arguments	`String`	`function_call` 类型必选）函数调用参数，JSON 字符串格式。
output	`String`	（`function_call_output` 类型必选）工具执行结果，JSON 字符串格式。

context.response参数：

参数	类型	说明
modalities	`array`	array 格式的字符串，模型输出模态设置，可选值： `["text"]`：仅输出文本。 `["audio", "text"]`（默认值）：同时输出文本和音频。
voice	string	覆盖本轮的 TTS 音色。

示例：

{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"杭州\",\"condition\":\"晴\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": [
        "text",
        "audio"
      ]
    },
    "type": "response.create"
  }
}

返回值说明 返回错误码，参见错误码查询。

nui_update_audio_data

当 audio_update_manually 设为 "true" 时，录音数据不再通过 onNuiNeedAudioData 填入，而是通过此接口主动推送。 方法签名

- (NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;

参数说明

参数	类型	说明
`data`	`const char *`	推送的音频数据。
`length`	`int`	推送的音频数据的字节数。
`first_pack`	`BOOL`	无需关注此参数。

返回值说明 返回错误码，参见错误码查询。

nui_push_reference_data

当 audio_update_manually 设为 "true" 且启用端侧 AEC 回声消除能力时，需要通过此接口推送播放器播放的音频数据作为参考信号。 方法签名

- (NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;

参数说明

参数	类型	说明
`data`	`const char *`	推送的音频数据。
`length`	`int`	推送的音频数据的字节数。
`first_pack`	`BOOL`	无需关注此参数。

返回值说明 返回错误码，参见错误码查询。

nui_release

释放SDK所有内部资源，并强制终止所有正在进行的任务。此方法调用后，SDK 实例将变为不可用状态，如需再次使用，必须重新调用 nui_initialize 进行初始化。 方法签名

- (NuiResultCode) nui_release;

返回值说明 返回错误码，参见错误码查询。

nui_get_version

获得当前SDK版本信息。此接口需在 nui_initialize 之后调用才有返回值。 方法签名

- (const char*) nui_get_version;

返回值说明 当前SDK版本信息。

nui_get_all_response

获得当前事件回调的完整信息。 方法签名

- (const char*) nui_get_all_response;

返回值说明 JSON 字符串格式的完整事件信息。

NeoNuiSdkDelegate：监听回调

onNuiEventCallback：监听事件信息

方法签名

- (void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;

参数说明

参数	类型	说明
`nuiEvent`	`NuiCallbackEvent`	回调事件。
`dialog`	`long`	会话编码，无需关注该参数。
`wuw`	`char*`	语音唤醒功能。无需关注该参数。
`asr_result`	`char*`	语音识别结果。
`finish`	`BOOL`	本轮识别是否结束标志。
`code`	`int`	错误码，在出现EVENT_ASR_ERROR事件时有效，参见错误码查询。

onNuiAudioStateChanged：监听音频状态

SDK 通过此回调通知何时应该开始或停止录音。 方法签名

- (void) onNuiAudioStateChanged:(NuiAudioState)state;

NuiAudioState状态说明

参数	说明
`STATE_OPEN`	交互启动，可以打开录音设备进行录音。
`STATE_PAUSE`	交互停止，可以停止录音。
`STATE_CLOSE`	SDK 实例已释放，可以彻底关闭录音设备。

onNuiNeedAudioData：填充待处理音频数据

开始对话后，该回调被连续触发，需在其中提供待处理的音频数据。参数audio_update_manually设置为"true"时可不关注这个回调。 方法签名

- (int) onNuiNeedAudioData:(char *)audioData length:(int)len;

参数说明

参数	类型	说明
`audioData`	`char *`	填充的音频数据。
`len`	`int`	填充的音频数据的字节数。

onNuiAssistEventCallback：辅助数据和信息结果

此回调用于接收 SDK 内部的辅助事件和相关数据。 方法签名

- (void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;

参数说明

参数	类型	说明
`nuiEvent`	`NuiCallbackEvent`	回调事件。
`info`	`char *`	无需关注此参数。
`info_len`	`int`	无需关注此参数。
`buffer`	`char *`	辅助数据，比如AI返回的TTS音频。
`len`	`int`	辅助数据的字节数。

onNuiLogTrackCallback：监听追踪日志

此回调用于接收 SDK 内部的详细日志，方便进行问题定位和调试。

- (void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent：事件类型

事件	说明
EVENT_TRANSCRIBER_STARTED	任务启动成功。
EVENT_VAD_START	任务启动后即触发该事件。不代表检测到人声起点。
EVENT_VAD_END	检测到人声终点。
EVENT_ASR_PARTIAL_RESULT	语音识别中间结果。
EVENT_ASR_ERROR	语音对话过程中出现错误。
EVENT_MIC_ERROR	因连续2秒未收到任何音频数据而触发。
EVENT_SENTENCE_END	检测到一句话结束，此时会返回一句完整的识别结果。
EVENT_TRANSCRIBER_COMPLETE	语音对话结束。
EVENT_AUDIO_TRANSCRIPTION	音频模式下的文字字幕增量事件，流式返回字幕片段。
EVENT_AUDIO_TRANSCRIPTION_COMPLETED	音频模式下的字幕输出完成事件。
EVENT_OTHER_RESULT	其他未归类事件信息，比如function_call的返回结果等。
EVENT_ASR_TTS_START	AI开始返回TTS数据。
EVENT_ASR_TTS_DATA	AI返回的TTS数据。
EVENT_ASR_TTS_COMPLETE	AI返回TTS数据结束。
EVENT_AEC_DATA	AEC回声消除后的音频数据。

​快速开始

​调用步骤

​请求参数

​连接与控制参数

​语音对话效果参数

​关键接口

​NeoNui

​nui_initialize

​nui_set_params

​nui_dialog_start

​nui_dialog_cancel

​nui_dialog_action

​nui_update_audio_data

​nui_push_reference_data

​nui_release

​nui_get_version

​nui_get_all_response

​NeoNuiSdkDelegate：监听回调

​onNuiEventCallback：监听事件信息

​onNuiAudioStateChanged：监听音频状态

​onNuiNeedAudioData：填充待处理音频数据

​onNuiAssistEventCallback：辅助数据和信息结果

​onNuiLogTrackCallback：监听追踪日志

​NuiCallbackEvent：事件类型

快速开始

调用步骤

请求参数

连接与控制参数

语音对话效果参数

关键接口

NeoNui

nui_initialize

nui_set_params

nui_dialog_start

nui_dialog_cancel

nui_dialog_action

nui_update_audio_data

nui_push_reference_data

nui_release

nui_get_version

nui_get_all_response

NeoNuiSdkDelegate：监听回调

onNuiEventCallback：监听事件信息

onNuiAudioStateChanged：监听音频状态

onNuiNeedAudioData：填充待处理音频数据

onNuiAssistEventCallback：辅助数据和信息结果

onNuiLogTrackCallback：监听追踪日志

NuiCallbackEvent：事件类型