Copy

使用者指南：非即時語音辨識。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求，請參見音訊規格。

快速開始

取得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 個使用。使用方法請參見即時熱詞。即時熱詞的適用模型及限制請參見即時熱詞。 `{ "张三": 5, "李四": 5 }`
`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" } }`

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

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;

傳回值說明 目前 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：監聽追蹤日誌

此回調用於接收 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	語音辨識過程中出現錯誤。

​快速開始

​呼叫步驟

​同步模式

​請求參數

​連線與控制參數

​語音辨識效果參數

​關鍵介面

​NeoNui

​nui_initialize

​nui_set_params

​nui_file_trans_start

​nui_file_trans_query

​nui_file_trans_cancel

​nui_release

​nui_get_version

​NeoNuiSdkDelegate：監聽回呼

​onFileTransEventCallback：監聽事件和語音辨識結果

​onFileTransLogTrackCallback：監聽追蹤日誌

​NuiCallbackEvent：事件類型

快速開始

呼叫步驟

同步模式

請求參數

連線與控制參數

語音辨識效果參數

關鍵介面

NeoNui

nui_initialize

nui_set_params

nui_file_trans_start

nui_file_trans_query

nui_file_trans_cancel

nui_release

nui_get_version

NeoNuiSdkDelegate：監聽回呼

onFileTransEventCallback：監聽事件和語音辨識結果

onFileTransLogTrackCallback：監聽追蹤日誌

NuiCallbackEvent：事件類型