Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash
非实时语音识别（Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash）iOS SDK
Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash非实时语音识别iOS SDK可将语音转换为文本。
用户指南：非实时语音识别。关于支持的音频格式、文件大小限制、时长限制等输入要求，请参见音频规格。
快速开始
- 获取API Key：获取API Key
- 下载SDK并运行示例代码：
- 下载最新SDK整合包。
- 解压 ZIP 包，将其中的 nuisdk.framework 添加到工程。
- 在 Build Phases → Link Binary With Libraries 中添加 nuisdk.xcframework。
- 在 General → Frameworks, Libraries, and Embedded Content 中将 nuisdk.xcframework 设置为 Embed & Sign。
- 用 Xcode 打开示例工程。示例代码位于
DashFunAsrFlashFileTranscriberViewController.m，替换 API Key 后体验功能。
调用步骤
同步模式
-
初始化 SDK
-
按业务需求配置相关参数
-
调用
nui_file_trans_start发送非实时语音识别请求。
-
在
onFileTransEventCallback接口中监听EVENT_FILE_TRANS_RESULT 事件，获取最终识别结果
-
调用
nui_release 释放 SDK 资源
请求参数
连接与控制参数
通过在nui_initialize接口的parameters参数中传入一个JSON字符串来配置。
参数示例：以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：
{
"url": "wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
"apikey": "st-****",
"device_id": "my_device_id",
"service_mode": "1"
}
| 参数 | 类型 | 是否必须 | 说明 |
|---|
url | String | 是 | 服务地址：
wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation- 华北2（北京）：
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation - 新加坡：
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
调用时，请将 {WorkspaceId} 替换为真实的 Workspace ID。 |
apikey | String | 是 | API Key。 |
service_mode | String | 是 | 运行模式。非实时语音识别固定为 "1"。 |
device_id | String | 是 | 用于标识终端用户的唯一字符串，可设为应用内用户ID或客户端生成的设备唯一标识符。此ID主要用于日志追踪和问题排查。 |
debug_path | String | 否 | 日志文件的存储路径。 此参数仅在调用nui_initialize接口时将save_log设为YES时生效。此时必须设置日志文件路径，否则将报错。 本地最多保留两个日志文件。 |
max_log_file_size | int | 否 | 设定日志文件的最大字节数。 此参数仅在调用nui_initialize接口时将save_log设为YES时生效。 默认值：104857600（100 * 1024 * 1024 字节, 即 100MiB）。 |
log_track_level | int | 否 | 控制通过日志回调（onFileTransLogTrackCallback）对外发送的日志内容的过滤级别。 默认值：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_file_trans_start接口配置所有语音识别效果参数。
参数示例：以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：
{
"apikey": "st-****",
"messages": [
{
"content": [
{
"input_audio": {
"data": "{YOUR_AUDIO_URL}"
},
"type": "input_audio"
}
],
"role": "user"
}
],
"nls_config": {
"format": "mp3",
"model": "qwen-audio-3.0-asr-flash"
}
}
| 参数 | 类型 | 是否必须 | 说明 |
|---|
apikey | string | 否 | 如果连接与控制参数的apikey使用的是临时API Key，可在此处进行更新，以免超时失效。 |
nls_config | object | 是 | 语音识别核心配置对象，包含模型选择、识别效果控制等关键参数。 |
nls_config.model | string | 是 | 指定示例调用的模型。模型信息请参见支持的模型与地域。 |
nls_config.format | string | 是 | 音频格式。根据实际音频格式填写，支持wav、mp3、opus等。详情请参见音频规格。 |
nls_config.sample_rate | string | 否 | 音频采样率，单位Hz。例如16000表示16kHz采样率。详情请参见音频规格。 |
nls_config.vocabulary_id | string | 否 | 预编译热词列表 ID。 需预先调用创建热词列表接口生成，识别时传入该 ID 即可使用列表中的热词。 适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。 使用方法请参见预编译热词。 |
nls_config.instant_vocabulary | object | 否 | 即时热词。
以键值对形式传入，键为热词文本（string），值为热词权重（integer），无需预先创建热词列表。权重取值范围为 [1, 5] 或 50：取 [1, 5] 时值越大模型越倾向输出该词；取 50 时为超级热词，召回率大幅提升，但超级热词数量最多不超过 50 个。
适用于临时性、会话级别的热词优化。
与预编译热词同时配置时，系统会合并两类热词；合并后超过 2000 个时，随机选择 2000 个使用。使用方法请参见即时热词。
|
nls_config.language_hints | array[string] | 否 | 设置待识别语言代码。如果无法提前确定语种，可不设置，模型会自动识别语种。
对于 Qwen-Audio-3.x-ASR-Flash 系列模型，最多支持设置 4 个值，即便设置超出 4 个，也仅前 4 个生效；对于 Fun-ASR-Flash 系列模型，仅支持设置 1 个值，即便设置多个，也仅第一个生效。
- Qwen-Audio-3.x-ASR-Flash、fun-asr-flash-2026-06-15：
- zh: 中文
- en: 英文
- ja: 日语
- ko：韩语
- vi：越南语
- th：泰语
- id：印尼语
- ms：马来语
- tl：菲律宾语
- hi：印地语
- ar：阿拉伯语
- fr：法语
- de：德语
- es：西班牙语
- pt：葡萄牙语
- ru：俄语
- it：意大利语
- nl：荷兰语
- sv：瑞典语
- da：丹麦语
- fi：芬兰语
- no：挪威语
- el：希腊语
- pl：波兰语
- cs：捷克语
- hu：匈牙利语
- ro：罗马尼亚语
- bg：保加利亚语
- hr：克罗地亚语
- sk：斯洛伐克语
|
| messages | array[object] | 是 | 消息列表。包含当前待识别的音频，以及可选的对话上下文（用于提升识别效果）。
详见如下说明。 |
messages参数说明：
上下文功能用于提升专有词汇的识别准确率，使用方法详见上下文增强。约束：上下文消息（input_text 和 text 类型）各最多 5 条，超出时保留最近的 5 条。每轮上下文文本总长度（user 和 assistant 的 text 字段长度之和）不超过 400 个字符（按字符数计算，每个字符计为 1），超出部分从末尾截断。 携带上下文时，messages 中的消息顺序有要求：上下文消息必须按对话轮次排列，每轮中 user（input_text 类型）必须在对应的 assistant（text 类型）之前；包含 input_audio 的 user 消息必须放在 messages 数组的最后。
| 参数 | 类型 | 是否必须 | 说明 |
|---|
| role | string | 是 | 消息角色。取值范围：
user（必选）：用户消息。type为input_audio时表示当前待识别的音频；type为input_text时表示前几轮的识别结果或领域相关的词表（可选，上下文）。assistant（可选，上下文）：前几轮大语言模型的回复内容。
|
| content | array[object] | 是 | 消息内容列表。详细如下说明。 |
content参数说明：
| 参数 | 类型 | 是否必须 | 说明 |
|---|
| type | string | 是 | 内容类型。每个请求至少需要一条input_audio类型的消息。取值范围：
input_audio（必选）：当前待识别的音频输入（role为user），需同时传入input_audio对象。input_text（可选，上下文）：前几轮用户语音的识别结果或领域相关的词表（role为user），需同时传入text字段。text（可选，上下文）：前几轮大语言模型的回复内容（role为assistant），需同时传入text字段。
|
| input_audio | object | 否 | 当type为input_audio时必填。 |
| input_audio.data | string | 是 | 待识别音频数据。关于支持的音频格式、文件大小限制、时长限制等输入要求，请参见音频规格。支持以下两种方式：
- 音频文件URL：直接传入可公开访问的音频文件地址。
- Base64 Data URI：采用Data URI格式传入Base64编码的音频数据，值由
data:{MIME_TYPE};base64,前缀与Base64编码的音频数据拼接而成。支持的MIME类型包括audio/wav、audio/mp3等。
示例（URL方式）：https://example.com/audio/sample.wav
示例（Base64方式）：data:audio/wav;base64,{BASE64_ENCODED_DATA} |
| text | string | 否 | 当type为input_text时，填入前几轮用户语音的识别结果或领域相关的词表；当type为text时，填入前几轮大语言模型的回复内容。文本按字符数计算，每个字符计为 1。每轮上下文中所有消息的 text 字段长度之和不超过 400 个字符，超出部分从末尾截断。 |
关键接口
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
此接口用于独立设置或更新 nls_config 参数。如果所有参数都在nui_file_trans_start中一次性提供，则无需调用此方法。
方法签名
- (NuiResultCode) nui_set_params:(const char *)params;
| 参数 | 类型 | 说明 |
|---|
params | char* | 语音识别效果参数中的nls_config和messages参数。
示例：
{
"messages": [
{
"content": [
{
"input_audio": {
"data": "{YOUR_AUDIO_URL}"
},
"type": "input_audio"
}
],
"role": "user"
}
],
"nls_config": {
"format": "mp3",
"model": "qwen-audio-3.0-asr-flash"
}
}
|
返回值说明
返回错误码，参见错误码查询。
nui_file_trans_start
开始识别。
方法签名
- (NuiResultCode) nui_file_trans_start:(const char *)params
taskId:(char *)task_id;
| 参数 | 类型 | 说明 |
|---|
params | char* | 语音识别效果参数。示例：{
"messages": [
{
"role": "user",
"content": [
{
"type": "input_audio",
"input_audio": {
"data": "{YOUR_AUDIO_URL}"
}
}
]
}
],
"nls_config": {
"format": "mp3",
"model": "qwen-audio-3.0-asr-flash"
}
}
|
task_id | char* | 可不关注，可填null |
返回值说明
返回错误码，参见错误码查询。
nui_file_trans_query
此非实时语音识别功能仅支持同步请求，无需关注此接口。
方法签名
- (NuiResultCode) nui_file_trans_query:(const char *)task_id;
| 参数 | 类型 | 说明 |
|---|
task_id | char* | 待查询的任务ID。通过EVENT_FILE_TRANS_UPLOADED获取。 |
返回值说明
返回错误码，参见错误码查询。
nui_file_trans_cancel
立即取消当前任务。
方法签名
- (NuiResultCode) nui_file_trans_cancel:(const char *)task_id;
| 参数 | 类型 | 说明 |
|---|
task_id | char* | 待取消的任务ID。通过EVENT_FILE_TRANS_UPLOADED获取。 |
返回值说明
返回错误码，参见错误码查询。
nui_release
释放SDK所有内部资源，并强制终止所有正在进行的任务。此方法调用后，SDK实例将变为不可用状态，如需再次使用，必须重新调用 nui_initialize 进行初始化。
方法签名
- (NuiResultCode) nui_release;
nui_get_version
获得当前SDK版本信息。
方法签名
- (const char*) nui_get_version;
NeoNuiSdkDelegate：监听回调
onFileTransEventCallback：监听事件和语音识别结果
方法签名
- (void) onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
asrResult:(const char *)asr_result
taskId:(const char *)task_id
ifFinish:(BOOL)finish
retCode:(int)code;
| 参数 | 类型 | 说明 |
|---|
nuiEvent | NuiCallbackEvent | 回调事件。 |
asr_result | char* | 语音识别结果。 |
task_id | char* | 任务ID。 |
finish | BOOL | 本轮识别是否结束标志。 |
code | int | 错误码，在出现EVENT_ASR_ERROR事件时有效，参见错误码查询。 |
onFileTransLogTrackCallback：监听追踪日志
此回调用于接收 SDK 内部的详细日志，方便进行问题定位和调试。
- (void)onFileTransLogTrackCallback:(NuiSdkLogLevel)level
logMessage:(const char *)log;
NuiCallbackEvent：事件类型
| 事件 | 说明 |
|---|
| EVENT_FILE_TRANS_CONNECTED | 连接服务成功。 |
| EVENT_FILE_TRANS_UPLOADED | 上传待识别音频文件成功，此时可获得当前任务的task_id。 |
| EVENT_FILE_TRANS_RESULT | 识别最终结果。 |
| EVENT_ASR_ERROR | 语音识别过程中出现错误。 |
