Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR非即時語音識別iOS SDK

​

快速開始

1. 取得API Key：取得API Key
2. 下載SDK並運行示例程式碼：
   • 下載最新SDK整合包。
   • 解壓 ZIP 包，將其中的 nuisdk.framework 添加到工程。
   • 在 Build Phases → Link Binary With Libraries 中添加 nuisdk.xcframework。
   • 在 General → Frameworks, Libraries, and Embedded Content 中將 nuisdk.xcframework 設定為 Embed & Sign。
   • 用 Xcode 打開示例工程。示例程式碼位於DashFunAsrFileTranscriberViewController.m，替換 API Key 後體驗功能。

​

呼叫步驟

​

請求參數

​

連接與控制參數

• 參數示例：以下為 JSON 字串示例，參數未完整列出。請按實際需求在編碼時補充：

{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

• 參數說明

  參數	類型	是否必須	說明
  url	String	是	服務地址： wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription 華北2（北京）：wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription 新加坡：wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription 呼叫時，請將 {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）的日誌才會被回呼。

​

語音識別效果參數

• 參數示例：以下為 JSON 字串示例，參數未完整列出。請按實際需求在編碼時補充：

{
    "apikey": "st-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}

• 參數說明

  參數	類型	是否必須	說明
  file_urls	array[string]	是	音視訊檔案轉寫的URL列表，支援HTTP / HTTPS協議，單次請求僅支援1個URL。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求，請參見音訊規格。若錄音檔案存儲在阿里雲OSS，使用RESTful API方式支援使用以oss://為前綴的臨時 URL，使用SDK方式不支援使用以 oss://為前綴的臨時 URL。 臨時 URL 有效期48小時，過期後無法使用，請勿用於生產環境。 檔案上傳憑證介面限流為 100 QPS 且不支援擴容，請勿用於生產環境、高並行及壓測場景。 生產環境建議使用阿里雲OSS 等穩定存儲，確保檔案長期可用並規避限流問題。 錄音檔案URL設定成OSS臨時公網訪問不通該如何處理？請求頭中將X-DashScope-OssResourceResolve設為enable（不推薦該方式）。 SDK不支援對請求頭進行設定。
  async_request	boolean	否	語音識別是否為非同步請求。預設值：false。取值範圍： true：非同步請求 false：同步請求
  apikey	string	否	如果連接與控制參數的apikey使用的是臨時API Key，可在此處進行更新，以免超時失效。
  nls_config	object	是	語音識別核心設定對象，包含模型選擇、識別效果控制等關鍵參數。
  nls_config.model	string	是	指定模型名。支援Qwen-Audio-3.0-ASR-Flash-Filetrans和Fun-ASR系列模型，詳情請參見支援的模型與地域。
  nls_config.special_word_filter	object	否	指定在語音識別過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。
  nls_config.channel_id	array[integer]	否	指定在多音軌音訊檔案中需要識別的音軌索引，索引從 0 開始。例如，[0] 表示識別第一個音軌，[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數，則預設處理第一個音軌。 指定的每一個音軌都將獨立計費。例如，為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。 預設值：[0]。
  nls_config.diarization_enabled	boolean	否	是否啓用說話人分離，預設關閉。僅適用於單聲道音訊，多聲道音訊不支援說話人分離。啓用該功能後，識別結果中將顯示speaker_id字段，用於區分不同說話人。 如果啓用說話人分離功能，建議音訊時長不超過2小時，否則可能導致識別失敗或超時。 預設值：false。有關speaker_id的示例，請參見識別結果說明。
  nls_config.speaker_count	integer	否	僅在開啓說話人分離功能（diarization_enabled設定為true）時生效。 說話人數量參考值。取值範圍為2至100的整數（包含2和100）。預設自動判斷說話人數量，如果設定此項，只能輔助算法盡量輸出指定人數，無法保證一定會輸出此人數。無預設值。
  nls_config.vocabulary_id	string	否	預編譯熱詞列表 ID。需預先呼叫建立熱詞列表介面生成，識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求復用同一詞表的場景。使用方法請參見預編譯熱詞。
  nls_config.input_context	array	否	消息列表，包含用於提升識別效果的可選對話上下文。 上下文功能用於提升專有詞彙的識別準確率，使用方法請參見上下文增強。上下文消息（input_text 和 text 類型）各最多 5 條，超出時保留最近的 5 條。每輪上下文文本總長度（user 和 assistant 的 text 字段長度之和）不超過 400 個字符，每個字符計為 1，超出部分從末尾截斷。 攜帶上下文時，messages 中的消息必須按對話輪次排列，每輪中 user（input_text 類型）必須在對應的 assistant（text 類型）之前；包含 input_audio 的 user 消息必須放在 messages 數組的最後。 Copy [ { "role": "user", "content": [ { "type": "input_text", "text": "你好啊，我是通义千问，有什么可以帮助你的？" } ] } ]
  nls_config.instant_vocabulary	object	否	即時熱詞，以鍵值對形式傳入：鍵為熱詞文本（string），值為熱詞權重（integer），無需預先建立熱詞列表。適用於臨時性、會話級別的熱詞優化。權重取值範圍為 1 至 5 或 50。取 1 至 5 時，值越大，模型越傾向於輸出該詞；取 50 時為超級熱詞，召回率大幅提升，但超級熱詞最多不超過 50 個。與預編譯熱詞同時設定時，系統會合併兩類熱詞；合併後超過 2000 個時，隨機選擇 2000 個使用。使用方法請參見即時熱詞。 僅 qwen-audio-3.0-asr-flash-filetrans 支援即時熱詞。 Copy { "张三": 5, "李四": 5 }
  nls_config.language_hints	array[string]	否	設定待識別語言程式碼。如果無法提前確定語種，可不設定，模型會自動識別語種。對於 Qwen-Audio-3.0-ASR-Flash-Filetrans 系列模型，最多支援設定 4 個值，即便設定超出 4 個，也僅前 4 個生效；對於 Fun-ASR 系列模型，僅支援設定 1 個值，即便設定多個，也僅第一個生效。 點擊查看支援的語言程式碼 qwen-audio-3.0-asr-flash-filetrans、fun-asr、fun-asr-2025-11-07、fun-asr-mtl、fun-asr-mtl-2025-08-25： 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：斯洛伐克語 fun-asr-2025-08-25： zh: 中文 en: 英文

​

關鍵介面

​

NeoNui

​

nui_initialize

• 方法簽名

-(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

• 方法簽名

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

• 參數說明

  參數	類型	說明
  params	char*	語音識別效果參數中的nls_config參數，nls_config之外的參數不支援通過該方法進行設定。示例： Copy { "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }

• 返回值說明

​

nui_file_trans_start

• 方法簽名

-(NuiResultCode) nui_file_trans_start:(const char *)params
                               taskId:(char *)task_id;

• 參數說明

  參數	類型	說明
  params	char*	語音識別效果參數。示例： Copy { "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }
  task_id	char*	任務ID，SDK內部生成隨機字串，在此介面呼叫成功後可獲得task_id。

• 返回值說明

​

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

• 方法簽名

-(NuiResultCode) nui_release;

• 返回值說明

​

nui_get_version

• 方法簽名

-(const char*) nui_get_version;

• 返回值說明 當前SDK版本資訊。

​

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：監聽追蹤日誌

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

​

NuiCallbackEvent：事件類型