Alibaba Cloud Model Studio：非即時語音辨識（Qwen-Audio-ASR）iOS SDK

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（表示關閉此功能）

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]

否

設定待辨識語言代碼。如果無法提前確定語種，可不設定，模型會自動辨識語種。最多支援設定 4 個值，超出時僅前 4 個生效。

指定語種代碼可提升辨識準確率。

messages

array[object]

是

訊息列表。包含當前待識別的音訊，以及可選的對話上下文（用於提升識別效果）。

role

string

是

訊息角色。取值範圍：

• user（必選）：使用者訊息。type為input_audio時表示當前待識別的音訊；type為input_text時表示前幾輪的識別結果或領域相關的詞表（可選，上下文）。

• assistant（可選，上下文）：前幾輪大型語言模型的回覆內容。

content

array[object]

是

訊息內容清單。詳細如下說明。

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 個字元，超出部分從末尾截斷。

parameters

char*

JSON字串，包含驗證、連線和偵錯參數。參見連線與控制參數。

level

NuiSdkLogLevel

控制 SDK 自身日誌的列印層級。

save_log

BOOL

是否儲存本機日誌。若為YES，須在連線與控制參數透過debug_path指定路徑，並可透過max_log_file_size設定檔案大小。

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*

語音識別效果參數。範例：

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

task_id

char*

待查詢的任務ID。透過EVENT_FILE_TRANS_UPLOADED獲取。

task_id

char*

待取消的任務ID。透過EVENT_FILE_TRANS_UPLOADED取得。

nuiEvent

NuiCallbackEvent

回調事件。

asr_result

char*

語音辨識結果。

task_id

char*

任務 ID。

finish

BOOL

本輪辨識是否結束標誌。

code

int

僅在出現 EVENT_ASR_ERROR 事件時有效。

EVENT_FILE_TRANS_CONNECTED

連線服務成功。

EVENT_FILE_TRANS_UPLOADED

上傳待辨識音訊檔案成功，此時可取得目前任務的task_id。

EVENT_FILE_TRANS_RESULT

辨識最終結果。

EVENT_ASR_ERROR

語音辨識過程中出現錯誤。