全部產品
Search
文件中心

Intelligent Speech Interaction:介面說明

更新時間:Oct 28, 2026

錄音檔案識別通過非同步任務將已錄製的音頻轉換為文本。提交可通過 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

  • http://127.0.0.1/sample.wav

  • D:\files\sample.wav

調用頻率與任務時效

識別結果查詢介面的使用者級 QPS 限制為 100。

超過調用頻率限制時會返回 Throttling.User。查詢任務時需設定輪詢間隔,控制請求頻率。

免費使用者每日可識別不超過 2 小時的錄音檔案。

提交任務後,免費使用者的任務在 24 小時內完成,付費使用者的任務在 6 小時內完成。識別結果在服務端儲存 72 小時。

重要

上述處理時效不適用於一次性提交大規模資料的情況,例如半小時內提交超過 500 小時的錄音。大規模識別需求請聯絡售前專家。

調用流程

  1. 根據音訊語種和採樣率,在專案中配置對應的識別模型。

  2. 準備可下載的錄音檔案 URL。

  3. 使用 POST 請求調用 SubmitTask,在 Task 參數中傳入任務配置。提交成功後,響應 JSON 的頂層 TaskId 欄位返回任務 ID。

  4. 擷取結果:輪詢方式使用該 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
}