大模型服务平台百炼：Qwen-Audio-3.0-Realtime实时语音对话iOS SDK

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>

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"：否

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（表示关闭此功能）

service_type

int

是

语音服务类型。实时语音对话固定为 4。

nls_config

object

是

语音对话核心配置对象，包含模型选择、对话效果控制等关键参数。

nls_config.model

string

是

指定模型名。支持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 音色名称，默认值为 longanqian。支持两种类型，仅可在第一次 session.update 中设置，后续传入将被忽略。

• 系统音色：可选值：longanqian、longanlingxin、longanlingxi、longanxiaoxin、longanlufeng。
• 声音复刻音色：通过声音复刻 API 创建，将返回的 voice_id 填入此参数。详见音色配置。

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 工具定义列表。配置后模型可根据用户输入自主决定是否调用工具。
内部参数说明：
typestring（必选）
固定为 function。
function.namestring（必选）
工具函数名称。
function.descriptionstring（可选）
对工具函数功能的描述，模型据此判断是否调用该工具。
function.parametersobject（可选）
对工具函数入参的描述，模型据此提取所需入参。若函数无需入参，可不指定。
示例：

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

parameters

char*

JSON 字符串，包含鉴权、连接和调试参数。参见连接与控制参数。

level

NuiSdkLogLevel

控制SDK自身日志的打印级别。

save_log

BOOL

是否保存本地日志。若为YES，须在连接与控制参数通过debug_path指定路径，并可通过max_log_file_size设置文件大小。

params

char*

语音对话效果参数。

vad_mode

NuiVadMode

VAD模式。固定为MODE_P2T。

dialog_params

char*

如果连接与控制参数的apikey参数使用的是临时API Key，当其过期时，可在此处进行更新。
内容为JSON 格式：

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

force

BOOL

是否强制结束而忽略最终结果。

• YES：不等待服务端返回最终识别结果就立即结束任务。
• NO：结束任务，但是会等待完整结果返回。

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时可设置，表示用于覆盖本轮推理的会话默认配置。不传时使用当前会话配置。详见如下。

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 编码）。

call_id

String

（function_call / function_call_output 类型必选）
函数调用的唯一标识符，用于关联请求和结果。

name

String

（function_call 类型必选）
要调用的函数名称。

arguments

String

function_call 类型必选）
函数调用参数，JSON 字符串格式。

output

String

（function_call_output 类型必选）
工具执行结果，JSON 字符串格式。

modalities

array

array 格式的字符串，模型输出模态设置，可选值：

• ["text"]：仅输出文本。
• ["audio", "text"]（默认值）：同时输出文本和音频。

voice

string

覆盖本轮的 TTS 音色。

data

const char *

推送的音频数据。

length

int

推送的音频数据的字节数。

first_pack

BOOL

无需关注此参数。

data

const char *

推送的音频数据。

length

int

推送的音频数据的字节数。

first_pack

BOOL

无需关注此参数。

nuiEvent

NuiCallbackEvent

回调事件。

dialog

long

会话编码，无需关注该参数。

wuw

char*

语音唤醒功能。无需关注该参数。

asr_result

char*

语音识别结果。

finish

BOOL

本轮识别是否结束标志。

code

int

错误码，在出现EVENT_ASR_ERROR事件时有效，参见错误码查询。

STATE_OPEN

交互启动，可以打开录音设备进行录音。

STATE_PAUSE

交互停止，可以停止录音。

STATE_CLOSE

SDK 实例已释放，可以彻底关闭录音设备。

audioData

char *

填充的音频数据。

len

int

填充的音频数据的字节数。

nuiEvent

NuiCallbackEvent

回调事件。

info

char *

无需关注此参数。

info_len

int

无需关注此参数。

buffer

char *

辅助数据，比如AI返回的TTS音频。

len

int

辅助数据的字节数。

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回声消除后的音频数据。