錄音檔案識別通過非同步任務將已錄製的音頻轉換為文本。提交可通過 HTTP 或 HTTPS 下載的檔案 URL 後,可輪詢查詢結果,也可通過回調接收結果;不支援直接提交本地檔案。
計費與服務版本
錄音檔案識別提供試用版和商用版,計費規則請參見計費說明。
新接入時建議在任務參數中顯式設定 version="4.0",該版本的輪詢和回調結果使用一致的駝峰命名欄位。舊版回調格式請參見歷史版本相容。
使用限制
檔案要求
支援 WAV、MP3、M4A、WMA、AAC、OGG、AMR、FLAC 錄音檔案,檔案大小不超過 512 MB。WAV、MP3 檔案支援單軌和雙軌。
音訊語種、採樣率需與專案中配置的識別模型匹配。模型選擇方式和支援範圍見語種和模型。
錄音檔案需存放在服務端可訪問的檔案伺服器上。URL 的主機名稱需使用網域名稱,不能使用 IP 位址;URL 不能包含空格,建議避免使用中文字元。
推薦將檔案存放在阿里雲 OSS。公用讀取檔案可使用可訪問的檔案 URL;私人檔案可使用預簽名 URL 。產生方式請參見使用預簽名 URL 下載或預覽檔案。
自行搭建的檔案伺服器需保證 HTTP 回應標頭 Content-Length 與響應體的實際長度一致。
可用URL | 不可用URL |
https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav |
|
調用頻率與任務時效
識別結果查詢介面的使用者級 QPS 限制為 100。
超過調用頻率限制時會返回 Throttling.User。查詢任務時需設定輪詢間隔,控制請求頻率。
免費使用者每日可識別不超過 2 小時的錄音檔案。
提交任務後,免費使用者的任務在 24 小時內完成,付費使用者的任務在 6 小時內完成。識別結果在服務端儲存 72 小時。
上述處理時效不適用於一次性提交大規模資料的情況,例如半小時內提交超過 500 小時的錄音。大規模識別需求請聯絡售前專家。
調用流程
根據音訊語種和採樣率,在專案中配置對應的識別模型。
準備可下載的錄音檔案 URL。
使用 POST 請求調用
SubmitTask,在Task參數中傳入任務配置。提交成功後,響應 JSON 的頂層TaskId欄位返回任務 ID。擷取結果:輪詢方式使用該
TaskId調用GetTaskResult;回調方式設定enable_callback=true和callback_url,任務完成後,服務端將結果 POST 到回調地址。
互動流程
用戶端與服務端的互動流程如下。任務 ID 位於響應 JSON 的 TaskId 欄位。

調用配置
介面採用 RPC 風格的 POP API,使用 AccessKey 簽名鑒權。SubmitTask 使用 POST,GetTaskResult 使用 GET。SDK 中的產品名稱為 nls-filetrans,地區、Endpoint 和 API 日期版本配置如下:
地區 | regionId / endpointName | domain | API 日期版本(Version) |
新加坡 | ap-southeast-1 | filetrans.ap-southeast-1.aliyuncs.com | 2019-08-23 |
API 日期版本 Version 用於配置 POP 請求;任務參數中的小寫 version 用於選擇錄音檔案識別的服務版本。
請求說明
提交任務:SubmitTask
將以下 JSON 對象序列化為字串,作為 Task 參數傳入 POST 請求。樣本中的 valid_times 僅識別指定時間段;需要識別整個檔案時可省略該欄位。
{
"appkey": "your-appkey",
"file_link": "https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav",
"auto_split":false,
"version": "4.0",
"enable_words": false,
"enable_sample_rate_adaptive": true,
"valid_times": [
{
"begin_time": 200,
"end_time":2000,
"channel_id": 0
}
]
}Task 欄位
參數 | 實值型別 | 是否必選 | 說明 |
appkey | String | 是 | 專案的 Appkey。專案中配置的識別模型需與音訊語種和採樣率匹配。 |
file_link | String | 是 | 錄音檔案的 HTTP 或 HTTPS 下載地址。服務端需能夠通過該地址下載檔案。 |
version | String | 否 | 任務使用的服務版本。未設定時預設為 2.0;新接入時建議顯式設定為 4.0。回調格式相容說明請參見歷史版本相容。 |
enable_words | Boolean | 否 | 是否返回詞資訊。預設值為 false。開啟時需設定 version 為 4.0。 |
enable_sample_rate_adaptive | Boolean | 否 | 是否將高於 16 kHz 的音頻自動降採樣至 16 kHz。預設值為 false。開啟時需設定 version 為 4.0。 |
enable_callback | Boolean | 否 | 是否啟用回調。預設值為 false。 |
callback_url | String | 否 | 回調服務地址。enable_callback 為 true 時必填。支援 HTTP 和 HTTPS,主機名稱需使用網域名稱,不能使用 IP 位址。回調服務需能夠接收 POST 請求。 |
auto_split | Boolean | 否 | 是否啟用智能分軌,通過句子結果中的 ChannelId 區分說話人。通常先發言的一方 ChannelId 為 0。支援 8 kHz 單通道音頻。 |
enable_unify_post | Boolean | 否 | 是否啟用後處理。預設值為 false。auto_split 和 enable_unify_post 不能同時為 true。 |
enable_inverse_text_normalization | Boolean | 否 | 是否啟用逆文本正常化(ITN),將中文數字轉換為阿拉伯數字。預設值為 false。開啟時需設定 version 為 4.0、enable_unify_post 為 true。不會對詞資訊進行 ITN 轉換。 |
enable_disfluency | Boolean | 否 | 是否啟用聲音順滑。預設值為 false。開啟時需設定 version 為 4.0、enable_unify_post 為 true。 |
valid_times | List< ValidTime > | 否 | 有效時間段列表,用於僅識別指定的音頻片段。每個元素的欄位見下方 ValidTime 欄位說明。 |
max_end_silence | Integer | 否 | 允許的最大結束靜音,預設值為 450 ms。 |
max_single_segment_time | Integer | 否 | 單句話的最大時間長度,最小值為 10000 ms,預設值為 20000 ms。 |
customization_id | String | 否 | 通過 POP API 建立的定製語言模型 ID。預設不設定。 |
class_vocabulary_id | String | 否 | 類熱詞表 ID。預設不設定。 |
vocabulary_id | String | 否 | 泛熱詞表 ID。預設不設定。 |
ValidTime 欄位
valid_times 的每個元素包含以下欄位:
參數 | 實值型別 | 是否必選 | 說明 |
begin_time | Int | 是 | 有效時間段的起始點時間位移,單位為毫秒。 |
end_time | Int | 是 | 有效時間段的結束點時間位移,單位為毫秒。 |
channel_id | Int | 是 | 有效時間段的作用音軌序號(從0開始)。 |
查詢結果:GetTaskResult
將提交響應中的任務 ID 作為 TaskId 參數傳入 GET 請求,並按使用限制設定查詢間隔。
屬性 | 實值型別 | 是否必選 | 說明 |
TaskId | String | 是 | 識別任務ID。 |
返回說明
HTTP 狀態表示 API 請求的處理結果,任務的識別狀態由響應 JSON 中的 StatusCode 和 StatusText 表示。
提交響應
提交成功時返回以下 JSON:
{
"TaskId": "4b56f0c4b7e611e88f34c33c2a60****",
"RequestId": "E4B183CC-6CFE-411E-A547-D877F7BD****",
"StatusText": "SUCCESS",
"StatusCode": 21050000
}屬性 | 實值型別 | 是否必選 | 說明 |
TaskId | String | 是 | 識別任務ID。 |
RequestId | String | 是 | 請求ID,僅用於聯調。 |
StatusCode | Int | 是 | 狀態代碼。 |
StatusText | String | 是 | 狀態說明。 |
查詢響應
識別成功
以下為單軌中文錄音nls-sample-16k.wav的識別結果樣本。
{
"TaskId": "d429dd7dd75711e89305ab6170fe****",
"RequestId": "9240D669-6485-4DCC-896A-F8B31F94****",
"StatusText": "SUCCESS",
"BizDuration": 2956,
"SolveTime": 1540363288472,
"StatusCode": 21050000,
"Result": {
"Sentences": [{
"EndTime": 2365,
"SilenceDuration": 0,
"BeginTime": 340,
"Text": "北京的天氣。",
"ChannelId": 0,
"SpeechRate": 177,
"EmotionValue": 5.0
}]
}
}排隊中
任務尚未開始識別,等待後重新查詢。
{
"TaskId": "c7274235b7e611e88f34c33c2a60****",
"RequestId": "981AD922-0655-46B0-8C6A-5C836822****",
"StatusText": "QUEUEING",
"StatusCode": 21050002
}識別中
任務正在識別,等待後重新查詢。
{
"TaskId": "c7274235b7e611e88f34c33c2a60****",
"RequestId": "8E908ED2-867F-457E-82BF-4756194A****",
"StatusText": "RUNNING",
"BizDuration": 0,
"StatusCode": 21050001
}識別失敗
以下為檔案下載失敗的響應樣本。根據 StatusCode 和 StatusText 處理錯誤。
{
"TaskId": "4cf25b7eb7e711e88f34c33c2a60****",
"RequestId": "098BF27C-4CBA-45FF-BD11-3F532F26****",
"StatusText": "FILE_DOWNLOAD_FAILED",
"BizDuration": 0,
"SolveTime": 1536906469146,
"StatusCode": 41050002
}響應欄位
Sentences 和 Words 位於 Result 對象中。
屬性 | 實值型別 | 是否必選 | 說明 |
TaskId | String | 是 | 識別任務ID。 |
StatusCode | Int | 是 | 狀態代碼。 |
StatusText | String | 是 | 狀態說明。 |
RequestId | String | 是 | 請求ID,用於調試。 |
Result | Object | 否 | 任務成功時返回的識別結果對象。排隊、運行中或失敗響應不包含該對象。 |
Sentences | List< SentenceResult > | 否 | Result 中的句子結果清單,StatusText 為 SUCCESS 時返回。 |
Words | List< WordResult > | 否 | Result 中的詞資訊列表。需設定 enable_words 為 true,且 version 為 4.0。 |
BizDuration | Long | 否 | 識別音訊時間長度,單位為毫秒。 |
SolveTime | Long | 否 | 識別完成時間的 Unix 時間戳記,單位為毫秒。任務尚未完成時不返回。 |
Sentences 欄位
屬性 | 實值型別 | 是否必選 | 說明 |
ChannelId | Int | 是 | 該句所屬音軌ID。 |
BeginTime | Int | 是 | 該句的起始時間位移,單位為毫秒。 |
EndTime | Int | 是 | 該句的結束時間位移,單位為毫秒。 |
Text | String | 是 | 該句的識別文本結果。 |
EmotionValue | Float | 是 | 情緒能量值,取值為音量分貝值除以 10,範圍為 1~10。 |
SilenceDuration | Int | 是 | 本句與上一句之間的靜音時間長度,單位為秒。 |
SpeechRate | Int | 是 | 本句的平均語速。
|
回調結果
設定 enable_callback=true、callback_url 和 version="4.0" 後,任務完成時服務端向回調地址發送 POST 請求。識別結果欄位與輪詢方式一致,樣本如下:
{
"Result": {
"Sentences": [{
"EndTime": 2365,
"SilenceDuration": 0,
"BeginTime": 340,
"Text": "北京的天氣。",
"ChannelId": 0,
"SpeechRate": 177,
"EmotionValue": 5.0
}]
},
"TaskId": "36d01b244ad811e9952db7bb7ed2****",
"StatusCode": 21050000,
"StatusText": "SUCCESS",
"RequestTime": 1553062810452,
"SolveTime": 1553062810831,
"BizDuration": 2956
}RequestTime 為提交任務時的 Unix 時間戳記,SolveTime 為識別完成時的 Unix 時間戳記,單位均為毫秒。
詞資訊
設定 enable_words=true 且 version="4.0" 後,結果中包含 Words。輪詢和回調返回的詞資訊一致。以下為中文錄音的結果樣本:
{
"StatusCode": 21050000,
"Result": {
"Sentences": [{
"SilenceDuration": 0,
"EmotionValue": 5.0,
"ChannelId": 0,
"Text": "北京的天氣。",
"BeginTime": 340,
"EndTime": 2365,
"SpeechRate": 177
}],
"Words": [{
"ChannelId": 0,
"Word": "北京",
"BeginTime": 640,
"EndTime": 940
}, {
"ChannelId": 0,
"Word": "的",
"BeginTime": 940,
"EndTime": 1120
}, {
"ChannelId": 0,
"Word": "天氣",
"BeginTime": 1120,
"EndTime": 2020
}]
},
"SolveTime": 1553236968873,
"StatusText": "SUCCESS",
"RequestId": "027B126B-4AC8-4C98-9FEC-A031158F****",
"TaskId": "b505e78c4c6d11e9a213e11db149****",
"BizDuration": 2956
}Words 欄位
屬性 | 實值型別 | 是否必選 | 說明 |
BeginTime | Int | 是 | 詞開始時間,單位為毫秒。 |
EndTime | Int | 是 | 詞結束時間,單位為毫秒。 |
ChannelId | Int | 是 | 該詞所屬音軌ID。 |
Word | String | 是 | 詞資訊。 |
狀態與錯誤處理
StatusCode | StatusText | 說明 |
21050000 | SUCCESS | SubmitTask:任務提交成功。GetTaskResult:任務識別成功。 |
21050001 | RUNNING | 任務正在識別,等待後重新查詢。 |
21050002 | QUEUEING | 任務正在排隊,等待後重新查詢。 |
21050003 | SUCCESS_WITH_NO_VALID_FRAGMENT | 任務完成,但未檢測到有效語音片段。檢查檔案是否包含有效語音。 |
錯誤碼
狀態代碼 | 狀態訊息 | 原因及處理方法 |
41050001 | USER_BIZDURATION_QUOTA_EXCEED | 超出單日識別時間長度限制。如業務量較大,請聯絡商務洽談,郵件地址:nls_support@service.aliyun.com。 |
41050002 | FILE_DOWNLOAD_FAILED | 檔案下載失敗。檢查檔案地址及服務端是否可以下載檔案。 |
41050003 | FILE_CHECK_FAILED | 檔案格式不符合要求。使用支援的錄音檔案格式。 |
41050004 | FILE_TOO_LARGE | 檔案過大。檢查錄音檔案大小是否超過 512 MB。 |
41050005 | FILE_NORMALIZE_FAILED | 檔案歸一化失敗。檢查檔案是否損壞、是否可以正常播放。 |
41050006 | FILE_PARSE_FAILED | 檔案解析失敗。檢查檔案是否損壞、是否可以正常播放。 |
41050007 | MKV_PARSE_FAILED | MKV 解析失敗。檢查檔案是否損壞、是否可以正常播放。 |
41050008 | UNSUPPORTED_SAMPLE_RATE | 音頻採樣率與專案模型不匹配。檢查音頻採樣率是否與 Appkey 所屬專案配置的識別模型採樣率一致。 |
41050009 | UNSUPPORTED_ASR_GROUP | 不支援的識別分組。檢查 Appkey 是否正確,以及是否與簽名使用的 AccessKey 屬於同一帳號。 |
41050010 | FILE_TRANS_TASK_EXPIRED | TaskId 不存在或任務已到期。檢查任務 ID 和結果儲存時間。 |
41050011 | REQUEST_INVALID_FILE_URL_VALUE | file_link 非法。檢查檔案 URL 的格式和可訪問性。 |
41050012 | REQUEST_INVALID_CALLBACK_VALUE | callback_url 非法。啟用回調時需提供有效回調 URL。 |
41050013 | REQUEST_PARAMETER_INVALID | 任務參數無效。Task 需為有效 JSON 字串。 |
41050014 | REQUEST_EMPTY_APPKEY_VALUE | appkey 為空白。填寫專案的 Appkey。 |
41050015 | REQUEST_APPKEY_UNREGISTERED | appkey 未註冊或不匹配。檢查 Appkey 是否正確,以及是否與簽名使用的 AccessKey 屬於同一帳號。 |
41050021 | RAM_CHECK_FAILED | RAM 許可權檢查失敗。為 RAM 使用者授予調用Voice Messaging Service API 的許可權。 |
41050023 | CONTENT_LENGTH_CHECK_FAILED | HTTP 響應的 Content-Length 與檔案實際大小不一致,修本文件伺服器的回應標頭。 |
41050024 | FILE_404_NOT_FOUND | 待下載的檔案不存在。檢查檔案地址。 |
41050025 | FILE_403_FORBIDDEN | 無許可權下載檔案。檢查是否有許可權下載錄音檔案。 |
41050026 | FILE_SERVER_ERROR | 檔案伺服器不可用。檢查檔案伺服器是否可用。 |
51050000 | INTERNAL_ERROR | 服務內部錯誤。偶發錯誤可忽略;重複出現時聯絡支援人員。 |
51050001 | VAD_FAILED | 語音活動檢測失敗。偶發錯誤可忽略;重複出現時聯絡支援人員。 |
51050002 | RECOGNIZE_FAILED | 識別失敗。偶發錯誤可忽略;重複出現時聯絡支援人員。 |
51050003 | RECOGNIZE_INTERRUPT | 識別中斷。偶發錯誤可忽略;重複出現時聯絡支援人員。 |
51050004 | OFFER_INTERRUPT | 寫入隊列中斷。偶發錯誤可忽略;重複出現時聯絡支援人員。 |
51050005 | FILE_TRANS_TIMEOUT | 任務處理逾時。偶發錯誤可忽略;重複出現時聯絡支援人員。 |
51050006 | FRAGMENT_FAILED | 音頻分段失敗。偶發錯誤可忽略;重複出現時聯絡支援人員。 |
語種和模型
語種和方言模型需在專案中配置,不能通過本介面的任務參數指定。支援語言模型定製和熱詞,詳情請參見語言模型定製和熱詞。
在Intelligent Speech Interaction控制台的全部專案頁面,選擇目標專案,進入專案功能配置,在修改配置中按音頻採樣率選擇模型。專案可選擇 8 kHz 或 16 kHz 的識別模型,具體選項見專案配置。操作方法請參見管理專案。
歷史版本相容
任務參數 version="2.0" 的回調結果採用底線命名欄位,與 4.0 的駝峰命名欄位不同。已按舊格式解析回調的應用,升級到 4.0 時需同步調整欄位解析。舊版回調樣本如下:
{
"result": [{
"begin_time": 340,
"channel_id": 0,
"emotion_value": 5.0,
"end_time": 2365,
"silence_duration": 0,
"speech_rate": 177,
"text": "北京的天氣。"
}],
"task_id": "3f5d4c0c399511e98dc025f34473****",
"status_code": 21050000,
"status_text": "SUCCESS",
"request_time": 1551164878830,
"solve_time": 1551164879230,
"biz_duration": 2956
}