接口說明
一句話識別功能支持對一分鐘內(nèi)的短語音進行識別，適用于對話聊天、控制口令、語音輸入法、語音搜索等較短的語音識別場景。
使用須知
如需使用Android/iOS SDK，請參見移動端接口說明。
支持的輸入格式：單聲道（mono）、16 bit采樣位數(shù)，包括PCM、PCM編碼的WAV、OGG封裝的OPUS、OGG封裝的SPEEX、AMR、MP3、AAC。
音頻采樣率：8000 Hz、16000 Hz。
時長限制：語音數(shù)據(jù)時長不能超過60s。
音頻文件大小：不超過2 MB。
支持情感分析：目前僅開放中文8k情感識別功能。
設(shè)置返回結(jié)果：
是否返回中間識別結(jié)果。
是否在后處理中添加標(biāo)點。
是否將中文數(shù)字轉(zhuǎn)為阿拉伯?dāng)?shù)字輸出。
設(shè)置多語言識別：在管控臺編輯項目中進行模型選擇，詳情請參見管理項目。
目前支持的語種和方言模型如下：
就近地域智能接入
一句話識別支持就近地域智能接入，域名為nls-gateway.aliyuncs.com。
推薦終端用戶使用就近地域接入域名。根據(jù)調(diào)用接口時客戶端所在的地理位置，系統(tǒng)會自動解析到最近的某個具體地域的服務(wù)器。例如在北京地域發(fā)起請求，系統(tǒng)會自動解析到北京地域的服務(wù)器，與指定域名nls-gateway-cn-beijing.aliyuncs.com實現(xiàn)效果一致。
服務(wù)地址
訪問類型 | 說明 | URL |
外網(wǎng)訪問（默認上海地域） | 所有服務(wù)器均可使用外網(wǎng)訪問URL（SDK中默認設(shè)置了外網(wǎng)訪問URL）。 |
|
ECS內(nèi)網(wǎng)訪問 | 使用阿里云上海、北京、深圳ECS（即ECS地域為華東2（上海）、華北2（北京）、華南1（深圳）），可使用內(nèi)網(wǎng)訪問URL。 ECS的經(jīng)典網(wǎng)絡(luò)不能訪問AnyTunnel，即不能在內(nèi)網(wǎng)訪問語音服務(wù)；如果希望使用AnyTunnel，需要創(chuàng)建專有網(wǎng)絡(luò)在其內(nèi)部訪問。 重要
|
|
交互流程
所有服務(wù)端的響應(yīng)都會在返回信息的header包含表示本次識別任務(wù)的task_id參數(shù)。
交互流程圖為Java SDK、C++ SDK、iOS SDK、Android SDK的交互流程，不包含RESTful API的交互流程，RESTful API的交互流程圖請參見RESTFUL API。
1.鑒權(quán)
客戶端與服務(wù)端建立WebSocket連接時，使用Token進行鑒權(quán)。關(guān)于Token獲取請參見獲取Token概述。
2.開始識別
客戶端發(fā)起一句話識別請求，服務(wù)端確認請求有效。
其中在請求消息中需要進行參數(shù)設(shè)置，各參數(shù)由SDK中SpeechRecognizer對象的相關(guān)set方法設(shè)置，各參數(shù)含義如下。
參數(shù) | 類型 | 是否必選 | 說明 |
appkey | String | 是 | 控制臺創(chuàng)建的項目Appkey。 |
format | String | 否 | 音頻格式，包括PCM、WAV、OPUS、SPEEX、AMR、MP3、AAC。 |
sample_rate | Integer | 否 | 音頻采樣率，默認值：16000 Hz。 根據(jù)音頻采樣率在管控臺對應(yīng)項目中配置支持該采樣率及場景的模型。 |
enable_intermediate_result | Boolean | 否 | 是否返回中間識別結(jié)果，默認值：False。 |
enable_punctuation_prediction | Boolean | 否 | 是否在后處理中添加標(biāo)點，默認值：False。 |
enable_inverse_text_normalization | Boolean | 否 | ITN（逆文本inverse text normalization）中文數(shù)字轉(zhuǎn)換阿拉伯?dāng)?shù)字。設(shè)置為True時，中文數(shù)字將轉(zhuǎn)為阿拉伯?dāng)?shù)字輸出，默認值：False。 |
disfluency | Boolean | 否 | 過濾語氣詞，即聲音順滑。默認值：False（關(guān)閉）。 |
customization_id | String | 否 | 自學(xué)習(xí)模型ID，具體可參見定制語言模型。 |
vocabulary_id | String | 否 | 定制泛熱詞ID，具體可參見在控制臺創(chuàng)建熱詞。 |
enable_voice_detection | Boolean | 否 | 是否啟動語音檢測。開啟后能夠識別出一段音頻中有效語音的開始和結(jié)束，剔除噪音數(shù)據(jù)。默認值：False（不開啟）。 |
max_start_silence | Integer | 否 | 當(dāng)enable_voice_detection設(shè)置為true時，該參數(shù)生效。表示允許的最大開始靜音時長。建議取值范圍：(0,60000]。單位：毫秒。 超出后（即開始識別后多時間沒有檢測到聲音）服務(wù)端將會發(fā)送TaskFailed事件，結(jié)束本次識別。 |
max_end_silence | Integer | 否 | 當(dāng)enable_voice_detection設(shè)置為true時，該參數(shù)生效。表示允許的最大結(jié)束靜音時長。單位：毫秒，取值范圍：200ms～6000ms。 超出時長服務(wù)端會發(fā)送RecognitionCompleted事件，結(jié)束本次識別（需要注意后續(xù)的語音將不會進行識別）。 |
audio_address | String | 否 | 可通過公網(wǎng)訪問的音頻文件下載鏈接。推薦使用阿里云OSS，具體請參見通過OSS如何獲取訪問URL。 |
special_word_filter | String（結(jié)構(gòu)為JSON格式） | 否 | 敏感詞過濾功能，支持開啟或關(guān)閉，支持自定義敏感詞。該參數(shù)可實現(xiàn)： 不處理（默認，即展示原文）、過濾、替換為*。 具體調(diào)用說明請見下文的自定義過濾詞調(diào)用示例。 說明 開啟但未配置敏感詞，則會過濾默認詞表：敏感詞表。 |
自定義過濾詞調(diào)用示例如下：
// 以實時轉(zhuǎn)寫為例，
JSONObject root = new JSONObject();
root.put("system_reserved_filter", true);
// 將以下詞語替換成空
JSONObject root1 = new JSONObject();
JSONArray array1 = new JSONArray();
array1.add("開始");
array1.add("發(fā)生");
root1.put("word_list", array1);
// 將以下詞語替換成*
JSONObject root2 = new JSONObject();
JSONArray array2 = new JSONArray();
array2.add("測試");
root2.put("word_list", array2);
// 可以全部設(shè)置，也可以部分設(shè)置
root.put("filter_with_empty", root1);
root.put("filter_with_signed", root2);
transcriber.addCustomedParam("special_word_filter", root);3.發(fā)送數(shù)據(jù)
循環(huán)發(fā)送語音數(shù)據(jù)，持續(xù)接收識別結(jié)果。
若enable_intermediate_result設(shè)置為true， 服務(wù)端會持續(xù)多次返回RecognitionResultChanged消息，即中間識別結(jié)果，示例如下：
北京的天 北京的天氣服務(wù)端返回的響應(yīng)消息：
{ "header": { "namespace": "SpeechRecognizer", "name": "RecognitionResultChanged", "status": 20000000, "message_id": "e06d2b5d50ca40d5a50d4215c7c8****", "task_id": "4c3502c7a5ce4ac3bdc488749ce4****", "status_text": "Gateway:SUCCESS:Success." }, "payload": { "result": "北京的天氣" } }header對象參數(shù)說明：
參數(shù)
類型
說明
namespace
String
消息所屬的命名空間。
name
String
消息名稱，RecognitionResultChanged表示獲取到中間識別結(jié)果。
status
Integer
狀態(tài)碼，表示請求是否成功，見服務(wù)狀態(tài)碼。
status_text
String
狀態(tài)消息。
task_id
String
任務(wù)全局唯一ID，請記錄該值，便于排查問題。
message_id
String
本次消息的ID。
payload對象參數(shù)說明：
參數(shù)
類型
說明
result
String
中間識別結(jié)果。
重要最后一次獲取的中間識別結(jié)果與最終的識別的結(jié)果不一定相同，請以RecognitionCompleted消息的最終識別結(jié)果為準(zhǔn)。
若enable_intermediate_result設(shè)置為false， 此步驟服務(wù)端不返回任何消息。
4.結(jié)束識別
客戶端發(fā)送停止一句話識別請求，通知服務(wù)端語音數(shù)據(jù)發(fā)送結(jié)束，停止語音識別，服務(wù)端返回最終識別結(jié)果：
{
"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對象參數(shù)說明：
參數(shù) | 類型 | 說明 |
namespace | String | 消息所屬的命名空間。 |
name | String | 消息名稱，RecognitionCompleted表示識別完成。 |
status | Integer | 狀態(tài)碼，表示請求是否成功，見服務(wù)狀態(tài)碼。 |
status_text | String | 狀態(tài)消息。 |
task_id | String | 任務(wù)全局唯一ID，請記錄該值，便于排查問題。 |
message_id | String | 本次消息的ID，由SDK自動生成。 |
payload對象參數(shù)說明：
參數(shù) | 類型 | 說明 |
result | String | 一句話識別的結(jié)果。 |
emo_tag | String | 當(dāng)前句子的情感，包含positive(正面情感，如開心、滿意）、negative(負面情感，如憤怒、沉悶、失望）、neutral (無明顯情感）三種類別。 |
emo_confidence | Double | 當(dāng)前句子識別情感的置信度，取值范圍：[0.0,1.0]。值越大表示置信度越高。 |
服務(wù)狀態(tài)碼
在服務(wù)的每一次響應(yīng)中，都包含status字段，即服務(wù)狀態(tài)碼，此處列舉通用錯誤碼、一句話識別錯誤碼表格，其取值含義如下。
通用錯誤碼
狀態(tài)碼 | 狀態(tài)消息 | 原因 | 解決方案 |
40000000 | 默認的客戶端錯誤碼，對應(yīng)了多個錯誤消息。 | 用戶使用了不合理的參數(shù)或者調(diào)用邏輯。 | 請參考官網(wǎng)文檔示例代碼進行對比測試驗證。 |
40000001 | The token 'xxx' has expired； The token 'xxx' is invalid | 用戶使用了不合理的參數(shù)或者調(diào)用邏輯。通用客戶端錯誤碼，通常是涉及Token相關(guān)的不正確使用，例如Token過期或者非法。 | 請參考官網(wǎng)文檔示例代碼進行對比測試驗證。 |
40000002 | Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'! | 無效或者錯誤的報文消息。 | 請參考官網(wǎng)文檔示例代碼進行對比測試驗證。 |
40000003 | PARAMETER_INVALID; Failed to decode url params | 用戶傳遞的參數(shù)有誤，一般常見于RESTful接口調(diào)用。 | 請參考官網(wǎng)文檔示例代碼進行對比測試驗證。 |
40000005 | Gateway:TOO_MANY_REQUESTS:Too many requests! | 并發(fā)請求過多。 | 如果是試用版調(diào)用，建議您升級為商用版本以增大并發(fā)。 如果已是商用版，可購買并發(fā)資源包，擴充您的并發(fā)額度。 |
40000009 | Invalid wav header! | 錯誤的消息頭。 | 如果您發(fā)送的是WAV語音文件，且設(shè)置 |
40000009 | Too large wav header! | 傳輸?shù)恼Z音WAV頭不合法。 | 建議使用PCM、OPUS等格式發(fā)送音頻流，如果是WAV，建議關(guān)注語音文件的WAV頭信息是否為正確的數(shù)據(jù)長度大小。 |
40000010 | Gateway:FREE_TRIAL_EXPIRED:The free trial has expired! | 試用期已結(jié)束，并且未開通商用版、或賬號欠費。 | 請登錄控制臺確認服務(wù)開通狀態(tài)以及賬戶余額。 |
40010001 | Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal | 不支持的接口或參數(shù)。 | 請檢查調(diào)用時傳遞的參數(shù)內(nèi)容是否和官網(wǎng)文檔要求的一致，并結(jié)合錯誤信息對比排查，設(shè)置為正確的參數(shù)。 比如您是否通過curl命令執(zhí)行RESTful接口請求， 拼接的URL是否合法。 |
40010003 | Gateway:DIRECTIVE_INVALID:[xxx] | 客戶端側(cè)通用錯誤碼。 | 表示客戶端傳遞了不正確的參數(shù)或指令，在不同的接口上有對應(yīng)的詳細報錯信息，請參考對應(yīng)文檔進行正確設(shè)置。 |
40010004 | Gateway:CLIENT_DISCONNECT:Client disconnected before task finished! | 在請求處理完成前客戶端主動結(jié)束。 | 無，或者請在服務(wù)端響應(yīng)完成后再關(guān)閉鏈接。 |
40010005 | Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping! | 客戶端發(fā)送了當(dāng)前不支持的消息指令。 | 請參考官網(wǎng)文檔示例代碼進行對比測試驗證。 |
40020105 | Meta:APPKEY_NOT_EXIST:Appkey not exist! | 使用了不存在的Appkey。 | 請確認是否使用了不存在的Appkey，Appkey可以通過登錄控制臺后查看項目配置。 |
40020106 | Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch! | 調(diào)用時傳遞的Appkey和Token并非同一個賬號UID所創(chuàng)建，導(dǎo)致不匹配。 | 請檢查是否存在兩個賬號混用的情況，避免使用賬號A名下的Appkey和賬號B名下生成的Token搭配使用。 |
403 | Forbidden | 使用的Token無效，例如Token不存在或者已過期。 | 請設(shè)置正確的Token。Token存在有效期限制，請及時在過期前獲取新的Token。 |
41000003 | MetaInfo doesn't have end point info | 無法獲取該Appkey的路由信息。 | 請檢查是否存在兩個賬號混用的情況，避免使用賬號A名下的Appkey和賬號B名下生成的Token搭配使用。 |
41010101 | UNSUPPORTED_SAMPLE_RATE | 不支持的采樣率格式。 | 當(dāng)前實時語音識別只支持8000 Hz和16000 Hz兩種采樣率格式的音頻。 |
41040201 | Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously! | 獲取客戶端發(fā)送的數(shù)據(jù)超時失敗。 | 客戶端在調(diào)用實時語音識別時請保持實時速率發(fā)送，發(fā)送完成后及時關(guān)閉鏈接。 |
50000000 | GRPC_ERROR:Grpc error! | 受機器負載、網(wǎng)絡(luò)等因素導(dǎo)致的異常，通常為偶發(fā)出現(xiàn)。 | 一般重試調(diào)用即可恢復(fù)。 |
50000001 | GRPC_ERROR:Grpc error! | 受機器負載、網(wǎng)絡(luò)等因素導(dǎo)致的異常，通常為偶發(fā)出現(xiàn)。 | 一般重試調(diào)用即可恢復(fù)。 |
52010001 | GRPC_ERROR:Grpc error! | 受機器負載、網(wǎng)絡(luò)等因素導(dǎo)致的異常，通常為偶發(fā)出現(xiàn)。 | 一般重試調(diào)用即可恢復(fù)。 |
一句話識別錯誤碼
狀態(tài)碼 | 狀態(tài)消息 | 原因 | 解決方案 |
40000000 | Gateway:CLIENT_ERROR:Empty audio data! | 沒有音頻數(shù)據(jù)。 | 建議參考公共云示例代碼，請求時發(fā)送音頻數(shù)據(jù)。 |
40000004 | Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time | 請求建立鏈接后，長時間沒有發(fā)送任何數(shù)據(jù)，超過10s后服務(wù)端會返回此錯誤信息。 | 請在建立鏈接后和服務(wù)端保持交互，比如持續(xù)發(fā)送語音流，您可以在采集音頻的同時進行發(fā)送， 發(fā)送結(jié)束后及時關(guān)閉鏈接。 |
40010002 | Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported! | 發(fā)送了服務(wù)端不支持的消息指令。 | 請參考官網(wǎng)文檔示例代碼進行對比測試驗證。 |
40010003 | Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173) | 熱詞數(shù)量設(shè)置過多。 | 請參考API進行正確設(shè)置。 |
40270002 | NO_VALID_AUDIO_ERROR | 無效的音頻。 | 從音頻中沒有識別出有效文本。 |
41010104 | TOO_LONG_SPEECH | 發(fā)送的語音時長超過限制，僅在一句話識別接口上出現(xiàn)。 | 一句話語音識別支持60s以內(nèi)的音頻，如果超過60s，建議調(diào)用實時語音識別接口。 |
41010105 | SILENT_SPEECH | 純靜音數(shù)據(jù)或噪音數(shù)據(jù)，導(dǎo)致無法檢測出任何有效語音。 | 無。 |