全部產品
Search
文件中心

Intelligent Speech Interaction:介面說明

更新時間:Oct 29, 2026

一句話識別將 60 秒以內的短語音轉換為文本,適用於對話聊天、控制口令、語音輸入法和語音搜尋等情境。用戶端通過 WebSocket 發送音頻流,接收識別事件和結果。

使用須知

音頻編碼和請求參數必須一致,否則可能導致識別失敗或結果為空白。

  • 聲道和採樣位元:單聲道、16 bit。

  • 音頻格式:PCM、PCM 編碼的 WAV、OGG 封裝的 OPUS、OGG 封裝的 SPEEX、AMR。

  • 採樣率:8000 Hz 或 16000 Hz。專案模型必須支援音頻所用的採樣率和語言。

  • 音頻時間長度:不超過 60 秒。

  • 音頻大小:不超過 2 MB。

通過請求參數可配置中間結果、標點和逆文本正則化(ITN)等功能。

選擇識別模型

語種和方言模型不能通過請求參數指定。在Intelligent Speech Interaction控制台的全部專案頁面,找到目標專案,單擊專案功能配置,選擇與音頻語言和採樣率匹配的模型。配置方法請參見管理專案。

可選模型以專案功能配置頁面為準。先選擇採樣率,再選擇對應的語言模型。

服務地址

通過公網使用以下 WebSocket 地址:wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1。

互動流程

以下流程適用於 WebSocket 及基於該協議的 SDK。RESTful API 的調用方式,請參見RESTful API。

所有服務端事件的 header 均包含本次識別任務的 task_id,可用於關聯請求、響應和排查問題。

1. 鑒權

用戶端建立 WebSocket 串連時,使用 NLS Token 進行鑒權。

Token 的擷取方法,請參見擷取 Token。

2. 開始識別

用戶端發送 StartRecognition 指令並設定識別參數。服務端確認請求有效後,返回 RecognitionStarted 事件。收到該事件後再發送音頻資料。

3. 發送資料

用戶端分塊發送二進位音頻資料,同時接收服務端事件。

  • enable_intermediate_result 為 true 時,服務端可多次返回 RecognitionResultChanged 中間結果。

  • enable_intermediate_result 為 false 時,不返回中間結果。服務端仍可能返回 RecognitionCompleted 或 TaskFailed,用戶端需要持續處理這些事件。

    重要

    最後一次中間結果可能與最終結果不同,以 RecognitionCompleted 中的結果為準。

4. 結束識別

音頻發送完畢後,用戶端發送 StopRecognition 指令。正常完成時,服務端返回 RecognitionCompleted 和最終結果;請求失敗時返回 TaskFailed。等待服務端結束事件後再關閉串連。

開啟語音檢測後,結束靜音時間長度超過 max_end_silence 時,服務端可提前完成識別,後續音頻不再識別。

請求參數

SDK 通過 SpeechRecognizer 對象提供的方法設定參數。直接使用 WebSocket 時,appkey 位於請求的 header 中,其餘識別參數位於 StartRecognition 的 payload 中。

參數

類型

是否必選

說明

appkey

String

是

在控制台建立的專案 Appkey。

format

String

否

音頻格式:pcm、wav、opus、speex、amr。WAV 使用 PCM 編碼,OPUS 和 SPEEX 使用 OGG 封裝。

sample_rate

Integer

否

音頻採樣率,單位為 Hz,預設值為 16000。取值為 8000 或 16000,必須與音頻及專案模型匹配。

enable_intermediate_result

Boolean

否

是否返回中間識別結果,預設值為 false。

enable_punctuation_prediction

Boolean

否

是否在後處理中添加標點,預設值為 false。

enable_inverse_text_normalization

Boolean

否

是否開啟逆文本正則化(ITN)。設定為 true 時,可將中文數字轉換為阿拉伯數字輸出。預設值為 false。

disfluency

Boolean

否

是否過濾語氣詞(順滑),預設值為 false。

customization_id

String

否

自學習模型 ID。配置方法請參見語言模型定製。

vocabulary_id

String

否

定製泛熱詞 ID。配置方法請參見定製熱詞。

enable_voice_detection

Boolean

否

是否開啟語音檢測。開啟後檢測有效語音的開始和結束,剔除噪音資料。預設值為 false。

max_start_silence

Integer

否

僅在 enable_voice_detection 為 true 時生效。允許的最大開始靜音時間長度,單位為毫秒,建議取值範圍為 (0, 60000]。超過該時間長度仍未檢測到有效語音時,服務端返回 TaskFailed 並結束識別。

max_end_silence

Integer

否

僅在 enable_voice_detection 為 true 時生效。允許的最大結束靜音時間長度,單位為毫秒,取值範圍為 200~6000。結束靜音時間長度超過該值時,服務端返回 RecognitionCompleted 並結束識別,後續音頻不再識別。

響應事件

header 的通用欄位如下。

參數

類型

說明

namespace

String

命名空間,取值為 SpeechRecognizer。

name

String

事件名稱,見下方各事件說明。

status

Integer

狀態代碼,20000000 表示成功,其他取值見服務狀態代碼。

status_text

String

狀態訊息。

task_id

String

本次識別任務的全域唯一 ID,與用戶端請求中的任務 ID 對應。記錄該值以便排查問題。

message_id

String

本條服務端響應訊息的 ID。

RecognitionStarted

服務端已接受開始識別請求,可以發送音頻資料。該事件不包含識別結果。

RecognitionResultChanged

返回中間識別結果,payload.result 為 String 類型。僅在 enable_intermediate_result 為 true 時返回。

{
  "header": {
    "namespace": "SpeechRecognizer",
    "name": "RecognitionResultChanged",
    "status": 20000000,
    "message_id": "f2bc60c1fd834da1bef7b9929fd1****",
    "task_id": "7ce7bac115844c109c680da4bf28****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "result": "開始測試今天北京的天氣很好我想購買三十二個蘋果請撥打到電話一二三四五結束測試"
  }
}

RecognitionCompleted

識別正常完成,payload.result 為 String 類型,表示最終結果。

{
  "header": {
    "namespace": "SpeechRecognizer",
    "name": "RecognitionCompleted",
    "status": 20000000,
    "message_id": "22ac941179bf45a8989d660bd9e8****",
    "task_id": "7ce7bac115844c109c680da4bf28****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "result": "開始測試今天北京的天氣很好我想購買三十二個蘋果請撥打到電話一二三四五結束測試"
  }
}

TaskFailed

識別任務失敗。根據 header.status 和 header.status_text 排查原因。例如,未發送音頻資料就結束請求,會返回 40000000 和 Gateway:CLIENT_ERROR:Empty audio data!。

服務狀態代碼

結合 status 和 status_text 判斷錯誤。同一狀態代碼可能對應不同原因,應以具體狀態訊息為準。

通用錯誤碼

狀態代碼

狀態訊息

原因

解決方案

40000000

預設的用戶端錯誤碼,對應了多個錯誤訊息。

使用了不合理的參數或調用邏輯。

檢查請求參數、指令順序及具體狀態訊息。

40000001

The token 'xxx' has expired.

The token 'xxx' is invalid

Token 到期或無效。

擷取有效 NLS Token 後重新調用。

40000002

Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!

訊息無效,或當前任務狀態不接受該訊息。

檢查訊息結構和指令順序。任務失敗後重新發起識別。

40000003

PARAMETER_INVALID;

Failed to decode url params

參數無效。

檢查參數名稱、類型和值是否符合介面要求。

40000005

Gateway:TOO_MANY_REQUESTS:Too many requests!

並發請求過多。

降低同時進行的請求數,並檢查可用並發額度。

40000009

Invalid wav header!

錯誤的訊息頭。

如果發送的是WAV語音檔案,且設定format為wav,檢查該語音檔案的WAV頭是否正確,否則可能會被服務端拒絕。

40000009

Too large wav header!

傳輸的語音WAV頭不合法。

建議使用PCM、OPUS等格式發送音頻流,如果是WAV,建議關注語音檔案的WAV頭資訊是否為正確的資料長度大小。

40000010

Gateway:FREE_TRIAL_EXPIRED:The free trial has expired!

試用期已結束且未開通商用版,或帳號欠費。

在控制台檢查一句話識別服務的開通狀態和賬戶餘額。

40010001

Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal

使用了不支援的介面或參數。

檢查服務地址、命名空間和參數是否符合介面要求。

40010003

Gateway:DIRECTIVE_INVALID:[xxx]

參數或指令無效。

根據具體狀態訊息檢查參數及指令。

40010004

Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!

任務完成前,用戶端主動中斷連線。

等待服務端返回任務結束事件後再關閉串連。

40010005

Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!

在當前任務狀態下發送了不支援的指令。

檢查指令順序,避免重複發送停止指令。

40020105

Meta:APPKEY_NOT_EXIST:Appkey not exist!

Appkey 不存在。

在控制台專案配置中核對 Appkey。

40020106

Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!

Appkey 與 Token 不屬於同一帳號。

使用同一帳號的專案 Appkey 和 NLS Token。

403

Forbidden

Token 不存在、到期或無效。

使用有效 NLS Token,並在到期前擷取新 Token。

41000003

MetaInfo doesn't have end point info

無法擷取 Appkey 的路由資訊。

檢查 Appkey,並確認 Appkey 與 Token 所屬帳號一致。

41010101

UNSUPPORTED_SAMPLE_RATE

採樣率不受當前配置支援。

確認音頻採樣率為 8000 Hz 或 16000 Hz,且與請求參數及專案模型匹配。

50000000

GRPC_ERROR:Grpc error!

服務端調用異常,可能與負載或網路有關。

重試請求;如問題持續存在,聯絡支援人員並提供 task_id。

50000001

GRPC_ERROR:Grpc error!

服務端調用異常,可能與負載或網路有關。

重試請求;如問題持續存在,聯絡支援人員並提供 task_id。

52010001

GRPC_ERROR:Grpc error!

服務端調用異常,可能與負載或網路有關。

重試請求;如問題持續存在,聯絡支援人員並提供 task_id。

一句話識別錯誤碼

狀態代碼

狀態訊息

原因

解決方案

40000000

Gateway:CLIENT_ERROR:Empty audio data!

未發送音頻資料。

發送非空的二進位音頻資料,再發送停止指令。

40000004

Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time

WebSocket 串連建立後,長時間未發送資料,空閑超過 10 秒。

建立串連後及時發送識別指令和音頻資料,音頻發送完畢後及時發送停止指令。

40010002

Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported!

發送了服務端不支援的指令。

檢查指令名稱,使用一句話識別介面支援的指令。

40010003

Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173)

熱詞數量過多。

按所用熱詞配置方式的數量限制調整熱詞。

40270002

NO_VALID_AUDIO_ERROR

音頻無效,未識別出有效文本。

檢查音頻是否包含清晰語音,以及編碼、採樣率和模型是否匹配。

41010104

TOO_LONG_SPEECH

音頻時間長度超過一句話識別限制。

使用 60 秒以內的音頻;較長語音使用即時語音辨識介面。

41010105

SILENT_SPEECH

靜音或噪音導致未檢測到有效語音。

檢查音頻內容;若開啟語音檢測,檢查開始靜音時間長度設定。