全部產品
Search
文件中心

Intelligent Speech Interaction:介面說明

更新時間:Sep 10, 2026

即時語音辨識通過 WebSocket 持續接收音頻流並返回識別結果,適用於會議演講、ApsaraVideo for Live等長時間不間斷識別情境。本文介紹服務地址、請求參數、識別事件和狀態代碼。

計費和並發限制

即時語音辨識提供試用版和商用版,費用說明請參見計費項目。

使用須知

調用介面前,確認音頻格式、採樣率和專案模型符合以下要求。

  • 支援的輸入格式:單聲道(mono)、16 bit 採樣位元,包括 PCM、PCM 編碼的 WAV、OGG 封裝的 OPUS。

  • 支援的音頻採樣率:8000 Hz、16000 Hz。

  • 支援設定返回結果:是否返回中間識別結果,在後處理中添加標點,將中文數字轉為阿拉伯數字輸出。

  • 不支援說話人分離,無法進行角色分析。

  • 識別使用的語種和方言由專案模型決定,不能通過請求參數指定。模型配置方法,請參見管理專案。

服務地址

訪問類型

說明

URL

外網訪問

使用新加坡地區的服務地址。

wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1

互動流程

說明

服務端響應的 header.task_id 標識本次識別任務。記錄該值,便於排查問題。

1. 鑒權

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

擷取方法,請參見通過 SDK 擷取 Token。

2. 開始識別

用戶端發送 StartTranscription 指令,並設定識別參數。服務端返回 TranscriptionStarted 後,用戶端開始發送音頻。使用 SDK 時,通過對應的參數設定方法完成配置。參數含義如下:

參數

類型

是否必選

說明

appkey

String

是

在Intelligent Speech Interaction控制台建立的專案 Appkey。

format

String

否

音頻格式:pcm、wav、opus。

sample_rate

Integer

否

音頻採樣率,預設是16000 Hz,根據音頻採樣率在控制台對應專案中配置支援該採樣率及情境的模型。

enable_intermediate_result

Boolean

否

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

enable_punctuation_prediction

Boolean

否

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

enable_inverse_text_normalization

Boolean

否

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

customization_id

String

否

自學習模型ID。

vocabulary_id

String

否

定製泛熱詞ID。

max_sentence_silence

Integer

否

靜音斷句閾值,單位為毫秒。檢測到語音後的靜音時間長度超過閾值時觸發斷句。取值範圍:200~2000,預設值:800。

開啟 enable_semantic_sentence_detection 後,不使用此閾值進行靜音斷句,但參數值仍需在允許範圍內。

靜音時間長度按音頻資料計算,不是停止發送資料後的等待時間長度。需要通過靜音斷句時,應持續發送包含靜音段的音頻;PCM 音訊靜音段可以用零值採樣表示。

enable_words

Boolean

否

是否開啟返回詞資訊,預設是false。

disfluency

Boolean

否

過濾語氣詞,即聲音順滑,預設值false(關閉)。

speech_noise_threshold

Float

否

噪音參數閾值,參數範圍:[-1,1]。取值說明如下:

  • 取值越趨於-1,噪音被判定為語音的機率越大。

  • 取值越趨於+1,語音被判定為噪音的機率越大。

重要

該參數屬進階參數,調整需謹慎並重點測試。

enable_semantic_sentence_detection

Boolean

否

是否開啟語義斷句,可選,預設是False。語義斷句參數需要和開啟中間結果配合使用,即開啟該語義斷句參數需將中間結果參數同時開啟:enable_intermediate_result=true。

3. 接收識別結果

用戶端持續發送音頻資料並接收識別事件。以下 JSON 樣本使用中文語音,展示各事件的訊息結構。

header對象參數說明:

參數

類型

說明

namespace

String

訊息所屬的命名空間。

name

String

事件名稱。

status

Integer

狀態代碼,表示請求是否成功,見服務狀態代碼。

status_text

String

狀態訊息。

task_id

String

任務全域唯一ID,請記錄該值,便於排查問題。

message_id

String

本次訊息的ID。

SentenceBegin

SentenceBegin事件表示服務端檢測到了一句話的開始。即時語音辨識服務的智能斷句功能會判斷出一句話的開始與結束,舉例如下:

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "SentenceBegin",
                "status": 20000000,
                "message_id": "a426f3d4618447519c9d85d1a0d1****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 0
        }
}

payload對象參數說明:

參數

類型

說明

index

Integer

句子編號,從1開始遞增。

time

Integer

當前已處理的音頻時間長度,單位為毫秒。

TranscriptionResultChanged

TranscriptionResultChanged事件表示識別結果發生了變化。僅當enable_intermediate_result取值為true時會多次返回此訊息,即一句話的中間識別結果,舉例如下:

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "TranscriptionResultChanged",
                "status": 20000000,
                "message_id": "dc21193fada84380a3b6137875ab****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 1835,
                "result": "北京的天",
                "confidence": 1.0,
                "words": [{
                        "text": "北京",
                        "startTime": 630,
                        "endTime": 930
                }, {
                        "text": "的",
                        "startTime": 930,
                        "endTime": 1110
                }, {
                        "text": "天",
                        "startTime": 1110,
                        "endTime": 1140
                }]
        }
}       

此事件的 header.name 為 TranscriptionResultChanged,表示句子的中間識別結果。

payload對象參數說明:

參數

類型

說明

index

Integer

句子編號,從1開始遞增。

time

Integer

當前已處理的音頻時間長度,單位為毫秒。

result

String

當前句子的識別結果。

words

List< Word >

當前句子的詞資訊,需要將enable_words設定為true。

confidence

Double

當前句子識別結果的信賴度,取值範圍:[0.0,1.0]。值越大表示信賴度越高。

SentenceEnd

SentenceEnd事件表示服務端檢測到了一句話的結束,並附帶返回該句話的識別結果,舉例如下:

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "SentenceEnd",
                "status": 20000000,
                "message_id": "c3a9ae4b231649d5ae05d4af36fd****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 1820,
                "begin_time": 0,
                "result": "北京的天氣。",
                "confidence": 1.0,
                "words": [{
                        "text": "北京",
                        "startTime": 630,
                        "endTime": 930
                }, {
                        "text": "的",
                        "startTime": 930,
                        "endTime": 1110
                }, {
                        "text": "天氣",
                        "startTime": 1110,
                        "endTime": 1380
                }]
        }
}

此事件的 header.name 為 SentenceEnd,表示識別到句子的結束。

payload對象參數說明:

參數

類型

說明

index

Integer

句子編號,從1開始遞增。

time

Integer

當前已處理的音頻時間長度,單位為毫秒。

begin_time

Integer

當前句子對應的SentenceBegin事件的時間,單位是毫秒。

result

String

當前的識別結果。

words

List< Word >

當前句子的詞資訊,需要將enable_words設定為true。

confidence

Double

當前句子識別結果的信賴度,取值範圍:[0.0,1.0]。值越大表示信賴度越高。

Words對象參數說明:

參數

類型

說明

text

String

文本。

startTime

Integer

詞開始時間,單位為毫秒。

endTime

Integer

詞結束時間,單位為毫秒。

4. 結束識別

音頻發送完成後,發送 StopTranscription 指令結束本次識別任務。服務端處理剩餘音頻,並在任務結束時返回 TranscriptionCompleted。收到該事件後再關閉串連。

StopTranscription 不是保持任務啟動並執行強制斷句指令。如果剩餘音頻中有有效語音,服務端可能先返回 SentenceEnd;僅包含靜音的任務不一定返回 SentenceEnd。

服務狀態代碼

通過響應中的 header.status 和 header.status_text 判斷請求狀態。下表列出常見錯誤及處理方法。

通用錯誤碼

狀態代碼

狀態訊息

原因

解決方案

40000000

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

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

請參考官網文檔範例程式碼進行對比測實驗證。

40000001

The token 'xxx' has expired;

The token 'xxx' is invalid

使用者使用了不合理的參數或者調用邏輯。通用用戶端錯誤碼,通常是涉及Token相關的不正確使用,例如Token到期或者非法。

請參考官網文檔範例程式碼進行對比測實驗證。

40000002

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

無效或者錯誤的報文訊息。

請參考官網文檔範例程式碼進行對比測實驗證。

40000003

PARAMETER_INVALID;

Failed to decode url params

使用者傳遞的參數有誤,一般常見於RESTful介面調用。

請參考官網文檔範例程式碼進行對比測實驗證。

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

不支援的介面或參數。

請檢查調用時傳遞的參數內容是否和官網文檔要求的一致,並結合錯誤資訊對比排查,設定為正確的參數。

比如是否通過curl命令執行RESTful介面請求, 拼接的URL是否合法。

40010003

Gateway:DIRECTIVE_INVALID:[xxx]

用戶端側通用錯誤碼。

表示用戶端傳遞了不正確的參數或指令,在不同的介面上有對應的詳細報錯資訊,請參考對應文檔進行正確設定。

40010004

Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!

在請求處理完成前用戶端主動結束。

收到 TranscriptionCompleted 後再關閉串連。

40010005

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

用戶端發送了當前不支援的訊息指令。

檢查指令發送順序。任務正在結束時,不要重複發送 StopTranscription。

40020105

Meta:APPKEY_NOT_EXIST:Appkey not exist!

使用了不存在的Appkey。

請確認是否使用了不存在的Appkey,Appkey可以通過登入控制台後查看專案配置。

40020106

Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!

調用時傳遞的Appkey和Token並非同一個帳號UID所建立,導致不匹配。

請檢查是否存在兩個帳號混用的情況,避免使用帳號A名下的Appkey和帳號B名下產生的Token搭配使用。

403

Forbidden

使用的Token無效,例如Token不存在或者已到期。

請設定正確的Token。Token存在有效期間限制,請及時在到期前擷取新的Token。

41000003

MetaInfo doesn't have end point info

無法擷取該Appkey的路由資訊。

請檢查是否存在兩個帳號混用的情況,避免使用帳號A名下的Appkey和帳號B名下產生的Token搭配使用。

41010101

UNSUPPORTED_SAMPLE_RATE

不支援的採樣率格式。

當前即時語音辨識只支援8000 Hz和16000 Hz兩種採樣率格式的音頻。

41040201

Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously!

擷取用戶端發送的資料逾時失敗。

按即時速率持續發送音頻。發送完成後發送 StopTranscription,收到 TranscriptionCompleted 後再關閉串連。

50000000

GRPC_ERROR:Grpc error!

受機器負載、網路等因素導致的異常,通常為偶發出現。

一般重試調用即可恢複。

50000001

GRPC_ERROR:Grpc error!

受機器負載、網路等因素導致的異常,通常為偶發出現。

一般重試調用即可恢複。

52010001

GRPC_ERROR:Grpc error!

受機器負載、網路等因素導致的異常,通常為偶發出現。

一般重試調用即可恢複。

即時語音辨識錯誤碼

狀態代碼

狀態訊息

原因

解決方案

40000004

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

請求建立串連後,長時間沒有發送任何資料,超過10s後,服務端會返回此錯誤資訊。

建立串連後持續發送音頻,可邊採集邊發送。音頻發送完成後發送 StopTranscription,收到 TranscriptionCompleted 後再關閉串連。

40270002

NO_VALID_AUDIO_ERROR

無效的音頻。

從音頻中沒有識別出有效文本。

40270003

DECODE_ERROR

音頻解碼失敗。

請根據實際音頻格式,設定對應的format參數。

41000002

APPKEY_KEY_IS_NULL

沒有正確設定appkey。

請參考官網文檔及範例程式碼。