一句話識別功能支援對一分鐘內的短語音進行識別，適用於對話聊天、控制口令、語音輸入法、語音搜尋等較短的語音辨識情境。
使用須知
如需使用Android/iOS SDK，請參見移動端介面說明。
支援的輸入格式：單聲道（mono）、16 bit採樣位元，包括PCM、PCM編碼的WAV、OGG封裝的OPUS、OGG封裝的SPEEX、AMR、MP3、AAC。
音頻採樣率：8000 Hz、16000 Hz。
時間長度限制：語音資料時間長度不能超過60s。
音頻檔案大小：不超過2 MB。
支援情感分析：目前僅開放中文8k情感識別功能。
設定返回結果：
是否返回中間識別結果。
是否在後處理中添加標點。
是否將中文數字轉為阿拉伯數字輸出。
設定多語言識別：在管控台編輯專案中進行模型選擇，詳情請參見管理專案。
目前支援的語種和方言模型如下：
就近地區智能接入
一句話識別支援就近地區智能接入，網域名稱為nls-gateway.aliyuncs.com。
推薦終端使用者使用就近地區接入網域名稱。根據調用介面時用戶端所在的地理位置，系統會自動解析到最近的某個具體地區的伺服器。例如在北京地區發起請求，系統會自動解析到北京地區的伺服器，與指定網域名稱nls-gateway-cn-beijing.aliyuncs.com實現效果一致。
服務地址
訪問類型 | 說明 | URL |
外網訪問 | 所有伺服器均可使用外網訪問URL（SDK中預設設定了外網訪問URL）。 | wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1 |
互動流程
所有服務端的響應都會在返回資訊的header包含表示本次識別任務的task_id參數。
互動流程圖為Java SDK、C++ SDK、iOS SDK、Android SDK的互動流程，不包含RESTful API的互動流程，RESTful API的互動流程圖請參見RESTFUL API。
1.鑒權
用戶端與服務端建立WebSocket串連時，使用Token進行鑒權。關於Token擷取請參見擷取Token概述。
2.開始識別
用戶端發起一句話識別請求，服務端確認請求有效。
其中在請求訊息中需要進行參數設定，各參數由SDK中SpeechRecognizer對象的相關set方法設定，各參數含義如下。
參數 | 類型 | 是否必選 | 說明 |
appkey | String | 是 | 控制台建立的專案Appkey。 |
format | String | 否 | 音頻格式，包括PCM、WAV、OPUS、SPEEX、AMR、MP3、AAC。 |
sample_rate | Integer | 否 | 音頻採樣率，預設值：16000 Hz。 根據音頻採樣率在管控台對應專案中配置支援該採樣率及情境的模型。 |
enable_intermediate_result | Boolean | 否 | 是否返回中間識別結果，預設值：False。 |
enable_punctuation_prediction | Boolean | 否 | 是否在後處理中添加標點，預設值：False。 |
enable_inverse_text_normalization | Boolean | 否 | ITN（逆文本inverse text normalization）中文數字轉換阿拉伯數字。設定為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時，該參數生效。表示允許的最大結束靜音時間長度。單位：毫秒，取值範圍：200ms～6000ms。 超出時間長度服務端會發送RecognitionCompleted事件，結束本次識別（需要注意後續的語音將不會進行識別）。 |
audio_address | String | 否 | 可通過公網訪問的音頻檔案下載連結。推薦使用阿里雲OSS，具體請參見通過OSS如何擷取訪問URL。 |
special_word_filter | String（結構為JSON格式） | 否 | 敏感詞過濾功能，支援開啟或關閉，支援自訂敏感詞。該參數可實現： 不處理（預設，即展示原文）、過濾、替換為*。 具體調用說明請見下文的自訂過濾詞調用樣本。 |
自訂過濾詞調用樣本如下：
// 以即時轉寫為例，
JSONObject root = new JSONObject();
root.put("system_reserved_filter", true);
// 將以下詞語替換成空
JSONObject root1 = new JSONObject();
JSONArray array1 = new JSONArray();
array1.add("開始");
array1.add("發生");
root1.put("word_list", array1);
// 將以下詞語替換成*
JSONObject root2 = new JSONObject();
JSONArray array2 = new JSONArray();
array2.add("測試");
root2.put("word_list", array2);
// 可以全部設定，也可以部分設定
root.put("filter_with_empty", root1);
root.put("filter_with_signed", root2);
transcriber.addCustomedParam("special_word_filter", root);3.發送資料
迴圈發送語音資料，持續接收識別結果。
若enable_intermediate_result設定為true， 服務端會持續多次返回RecognitionResultChanged訊息，即中間識別結果，樣本如下：
北京的天 北京的天氣服務端返回的響應訊息：
{ "header": { "namespace": "SpeechRecognizer", "name": "RecognitionResultChanged", "status": 20000000, "message_id": "e06d2b5d50ca40d5a50d4215c7c8****", "task_id": "4c3502c7a5ce4ac3bdc488749ce4****", "status_text": "Gateway:SUCCESS:Success." }, "payload": { "result": "北京的天氣" } }header對象參數說明：
參數
類型
說明
namespace
String
訊息所屬的命名空間。
name
String
訊息名稱，RecognitionResultChanged表示擷取到中間識別結果。
status
Integer
狀態代碼，表示請求是否成功，見服務狀態代碼。
status_text
String
狀態訊息。
task_id
String
任務全域唯一ID，請記錄該值，便於排查問題。
message_id
String
本次訊息的ID。
payload對象參數說明：
參數
類型
說明
result
String
中間識別結果。
重要最後一次擷取的中間識別結果與最終的識別的結果不一定相同，請以RecognitionCompleted訊息的最終識別結果為準。
若enable_intermediate_result設定為false， 此步驟服務端不返回任何訊息。
4.結束識別
用戶端發送停止一句話識別請求，通知服務端語音資料發送結束，停止語音辨識，服務端返回最終識別結果：
{
"header": {
"namespace": "SpeechRecognizer",
"name": "RecognitionCompleted",
"status": 20000000,
"message_id": "10490c992aef44eaa4246614838f****",
"task_id": "4c3502c7a5ce4ac3bdc488749ce4****",
"status_text": "Gateway:SUCCESS:Success."
},
"payload": {
"result": "北京的天氣。",
"emo_tag": "neutral",
"emo_confidence": 0.931
}
}header對象參數說明：
參數 | 類型 | 說明 |
namespace | String | 訊息所屬的命名空間。 |
name | String | 訊息名稱，RecognitionCompleted表示識別完成。 |
status | Integer | 狀態代碼，表示請求是否成功，見服務狀態代碼。 |
status_text | String | 狀態訊息。 |
task_id | String | 任務全域唯一ID，請記錄該值，便於排查問題。 |
message_id | String | 本次訊息的ID，由SDK自動產生。 |
payload對象參數說明：
參數 | 類型 | 說明 |
result | String | 一句話識別的結果。 |
emo_tag | String | 當前句子的情感，包含positive(正面情感，如開心、滿意）、negative(負面情感，如憤怒、沉悶、失望）、neutral (無明顯情感）三種類別。 |
emo_confidence | Double | 當前句子識別情感的信賴度，取值範圍：[0.0,1.0]。值越大表示信賴度越高。 |
服務狀態代碼
在服務的每一次響應中，都包含status欄位，即服務狀態代碼，此處列舉通用錯誤碼、一句話識別錯誤碼錶格，其取值含義如下。
通用錯誤碼
狀態代碼 | 狀態訊息 | 原因 | 解決方案 |
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語音檔案，且設定 |
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! | 在請求處理完成前用戶端主動結束。 | 無，或者請在服務端響應完成後再關閉連結。 |
40010005 | Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping! | 用戶端發送了當前不支援的訊息指令。 | 請參考官網文檔範例程式碼進行對比測實驗證。 |
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! | 擷取用戶端發送的資料逾時失敗。 | 用戶端在調用即時語音辨識時請保持即時速率發送，發送完成後及時關閉連結。 |
50000000 | GRPC_ERROR:Grpc error! | 受機器負載、網路等因素導致的異常，通常為偶發出現。 | 一般重試調用即可恢複。 |
50000001 | GRPC_ERROR:Grpc error! | 受機器負載、網路等因素導致的異常，通常為偶發出現。 | 一般重試調用即可恢複。 |
52010001 | GRPC_ERROR:Grpc error! | 受機器負載、網路等因素導致的異常，通常為偶發出現。 | 一般重試調用即可恢複。 |
一句話識別錯誤碼
狀態代碼 | 狀態訊息 | 原因 | 解決方案 |
40000000 | Gateway:CLIENT_ERROR:Empty audio data! | 沒有音頻資料。 | 建議參考公用雲範例程式碼，請求時發送音頻資料。 |
40000004 | Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time | 請求建立連結後，長時間沒有發送任何資料，超過10s後服務端會返回此錯誤資訊。 | 請在建立連結後和服務端保持互動，比如持續發送語音流，您可以在採集音訊同時進行發送， 發送結束後及時關閉連結。 |
40010002 | Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported! | 發送了服務端不支援的訊息指令。 | 請參考官網文檔範例程式碼進行對比測實驗證。 |
40010003 | Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173) | 熱詞數量設定過多。 | 請參考API進行正確設定。 |
40270002 | NO_VALID_AUDIO_ERROR | 無效的音頻。 | 從音頻中沒有識別出有效文本。 |
41010104 | TOO_LONG_SPEECH | 發送的語音時間長度超過限制，僅在一句話識別介面上出現。 | 一句話語音辨識支援60s以內的音頻，如果超過60s，建議調用即時語音辨識介面。 |
41010105 | SILENT_SPEECH | 純靜音資料或噪音資料，導致無法檢測出任何有效語音。 | 無。 |