本文介紹Qwen-Audio-ASR-Filetrans非即時語音辨識HTTP API的參數和介面細節。
關於支援的音頻格式、檔案大小限制、時間長度限制等輸入要求,請參見音頻規格。
流程說明
與DashScope同步調用(一次請求、立即返回結果)不同,非同步呼叫專為處理長音頻檔案或耗時較長的任務設計,該模式採用“提交-輪詢”的兩步式流程,避免了因長時間等待而導致的請求逾時:
-
第一步:提交任務
- 用戶端發起一個非同步處理請求。
- 伺服器驗證請求後,不會立即執行任務,而是返回一個唯一的
task_id,表示任務已成功建立。
-
第二步:擷取結果
- 用戶端使用擷取到的
task_id,通過輪詢方式反覆調用結果查詢介面。
- 當任務處理完成後,結果查詢介面將返回最終的識別結果。
介面地址
新加坡
提交任務介面:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
查詢任務介面:GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
調用時請將{WorkspaceId}替換為真實的Workspace ID。
華北2(北京)
提交任務介面:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
查詢任務介面:GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
調用時請將{WorkspaceId}替換為真實的Workspace ID。
重要阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
- 華北2(北京)地區:從
dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
- 新加坡地區:從
dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
要求標頭
| 參數 | 類型 | 是否必選 | 說明 |
|---|
Authorization
| string
| 是 | 鑒權令牌,格式為Bearer <your_api_key>,使用時,將"<your_api_key>"替換為實際的API Key。提交任務介面和查詢任務介面均需要傳入。 |
Content-Type
| string
| 是 | 請求參數的媒體類型。僅提交任務介面需要傳入,固定為application/json。 |
X-DashScope-Async
| string
| 是 | 非同步任務標識。僅提交任務介面需要傳入,固定為enable,請勿遺漏,否則無法提交任務。 |
提交任務介面
提交語音辨識任務。該介面非同步返回,業務側需結合查詢任務介面輪詢任務狀態。
說明調用獨享部署時,如果傳回 current user api does not support asynchronous calls,將 X-DashScope-Async 設為 disable,改用同步請求。
請求參數 modelstring(必選) 模型名稱。 inputobject(必選) 輸入參數對象。 屬性 file_urls array[string](必選) 音視頻檔案轉寫的URL列表,支援HTTP / HTTPS協議,單次請求僅支援1個URL。關於支援的音頻格式、檔案大小限制、時間長度限制等輸入要求,請參見音頻規格。 若錄音檔案儲存體在阿里雲OSS,使用RESTful API方式支援使用以oss://為首碼的臨時 URL,使用SDK方式不支援使用以 oss://為首碼的臨時 URL。 重要
-
臨時 URL 有效期間48小時,到期後無法使用,請勿用於生產環境。
-
檔案上傳憑證介面限流為 100 QPS 且不支援擴容,請勿用於生產環境、高並發及壓測情境。
-
生產環境建議使用阿里雲OSS 等穩定儲存,確保檔案長期可用並規避限流問題。
-
錄音檔案URL設定成OSS臨時公網訪問不通該如何處理?要求標頭中將X-DashScope-OssResourceResolve設為enable(不推薦該方式)。
SDK不支援對要求標頭進行配置。
contextarray(object)(可選) 訊息列表。包含可選的對話上下文(用於提升識別效果)。 重要上下文功能用於提升專有詞彙的識別準確率,使用方法詳見上下文增強。 約束:上下文訊息(input_text 和 text 類型)各最多 5 條,超出時保留最近的 5 條。每輪上下文文本總長度(user 和 assistant 的 text 欄位長度之和)不超過 400 個字元(按字元數計算,每個字元計為 1),超出部分從末尾截斷。 重要攜帶上下文時,messages 中的訊息順序有要求:上下文訊息必須按對話輪次排列,每輪中 user(input_text 類型)必須在對應的 assistant(text 類型)之前;包含 input_audio 的 user 訊息必須放在 messages 數組的最後。 屬性 rolestring(必選) 訊息角色。取值範圍:
user:前幾輪的識別結果或領域相關的詞表。
assistant:前幾輪大語言模型的回複內容。
contentarray(object)(必選) 訊息內容列表。 屬性 typestring(必選) 內容類型。取值範圍:
input_text(可選,上下文):前幾輪使用者語音的識別結果或領域相關的詞表(role為user),需同時傳入text欄位。
text(可選,上下文):前幾輪大語言模型的回複內容(role為assistant),需同時傳入text欄位。
textstring(條件必選) 當type為input_text時,填入前幾輪使用者語音的識別結果或領域相關的詞表;當type為text時,填入前幾輪大語言模型的回複內容。文本按字元數計算,每個字元計為 1。每輪上下文中所有訊息的 text 欄位長度之和不超過 400 個字元,超出部分從末尾截斷。 parametersobject(必選) 必須傳入 parameters;無需設定參數時傳入空物件 {}。省略此欄位會導致已提交的轉寫任務失敗。 屬性 keep_dialect boolean (可選) 僅 qwen-audio-3.1-asr-flash-filetrans 支援。預設值為 false:將方言轉寫為普通話;設為 true 時保留方言表達。 vocabulary_id string(可選) 先行編譯熱詞列表 ID。 需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。 適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。 使用方法請參見先行編譯熱詞。 vocabulary object(可選) 即時熱詞。 以索引值對形式傳入,鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50:取 [1, 5] 時值越大模型越傾向輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞數量最多不超過 50 個。 適用於臨時性、會話層級的熱詞最佳化。 與預編譯熱詞同時設定時,系統會合併兩類熱詞;合併後超過 2000 個時,隨機選擇 2000 個使用。使用方法請參見即時熱詞。 channel_id array[integer](可選) 指定在多音軌音頻檔案中需要識別的音軌索引,索引從 0 開始。例如,[0] 表示識別第一個音軌,[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數,則預設處理第一個音軌。 重要指定的每一個音軌都將獨立計費。例如,為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。 預設值:[0]。 special_word_filter string(可選) 設定需要替換或移除的詞語。參數值為 JSON 字串,包含以下欄位:
filter_with_signed.word_list:字串陣列,將相符詞替換為等長的 *。
filter_with_empty.word_list:字串陣列,將相符詞從結果中移除。
system_reserved_filter:布林值,預設 true,控制是否同時使用系統預置詞表;設為 false 時,自訂規則仍生效。
未傳入該參數時,使用系統內建的阿里雲百煉敏感詞表,將相符詞替換為等長的 *。 例如,以等長星號替換「測試」,並移除「開始」,參數值如下: {
"special_word_filter": "{\"filter_with_signed\":{\"word_list\":[\"测试\"]},\"filter_with_empty\":{\"word_list\":[\"开始\",\"发生\"]},\"system_reserved_filter\":true}"
}
diarization_enabled boolean(可選) 是否啟用說話人分離,預設關閉。 僅適用於單聲道音頻,多頻道音訊不支援說話人分離。 啟用該功能後,識別結果中將顯示speaker_id欄位,用於區分不同說話人。 說明如果啟用說話人分離功能,建議音頻時間長度不超過2小時,否則可能導致識別失敗或逾時。 有關speaker_id的樣本,請參見識別結果說明。 預設值:false。 speaker_count integer(可選) 重要僅在開啟說話人分離功能(diarization_enabled設定為true)時生效。 說話人數量參考值。取值範圍為2至100的整數(包含2和100)。 預設自動判斷說話人數量,如果配置此項,只能輔助演算法盡量輸出指定人數,無法保證一定會輸出此人數。 無預設值。 language_hints array[string](可選) 設定待識別語言代碼。如果無法提前確定語種,可不設定,模型會自動識別語種。 最多支援設定 4 個值,超出時僅前 4 個生效。 點擊查看支援的語言代碼
- zh: 中文
- en: 英文
- ja: 日語
- ko:韓語
- vi:越南語
- th:泰語
- id:印尼語
- ms:馬來語
- tl:菲律賓語
- hi:印地語
- ar:阿拉伯語
- fr:法語
- de:德語
- es:西班牙語
- pt:葡萄牙語
- ru:俄語
- it:意大利語
- nl:荷蘭語
- sv:瑞典語
- da:丹麥語
- fi:芬蘭語
- no:挪威語
- el:希臘語
- pl:波蘭語
- cs:捷克語
- hu:匈牙利語
- ro:羅馬尼亞語
- bg:保加利亞語
- hr:克羅地亞語
- sk:斯洛伐克語
| 普通調用以下為新加坡地區的配置,調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。新加坡地區和北京地區的API Key不同。 curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--header "X-DashScope-Async: enable" \
--data '{
"model": "qwen-audio-3.0-asr-flash-filetrans",
"input": {
"file_urls": [
"{YOUR_AUDIO_URL}"
]
},
"parameters": {
"channel_id": [0]
}
}'
即時熱詞使用即時熱詞時格式如下: {
"model": "qwen-audio-3.0-asr-flash-filetrans",
"input": {
"file_urls": [
"{YOUR_AUDIO_URL}"
]
},
"parameters": {
"vocabulary": {"張三": 5, "李四": 5}
}
}
上下文使用上下文時格式如下: {
"model": "qwen-audio-3.0-asr-flash-filetrans",
"input": {
"file_urls": [
"{YOUR_AUDIO_URL}"
],
"context": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "你好啊"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "你好啊,我是通義千問,有什麼可以協助你的?"
}
]
}
]
},
"parameters": {
"vocabulary": {"張三": 5, "李四": 5}
}
}
|
響應參數 request_idstring 本次調用的唯一識別碼。 outputobject 提交任務返回的資料。 屬性 task_idstring 任務ID。該ID在查詢任務介面中作為string傳入。 task_statusstring 任務狀態。提交成功時返回PENDING。 | {
"output": {
"task_status": "PENDING",
"task_id": "c2e5d63b-96e1-4607-bb91-************"
},
"request_id": "77ae55ae-be17-97b8-9942--************"
}
|
查詢任務介面
查詢語音辨識任務的執行情況和結果。建議輪詢調用直至任務終態。
請求參數 task_idstring(必選) 查詢任務需指定其ID,該ID為提交任務介面被調用後返回的task_id。 | 以下為新加坡地區的配置,調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。新加坡地區和北京地區的API Key不同。 curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
|
響應參數 request_idstring 本次調用的唯一識別碼。 outputobject 查詢任務返回的資料。 屬性 task_idstring 被查詢任務的ID。 task_statusstring 被查詢任務的狀態。 說明當任務包含多個子任務時,只要存在任一子任務成功,整個任務狀態將標記為SUCCEEDED,需通過subtask_status欄位判斷具體子任務結果。 submit_timestring 任務提交時間。 scheduled_timestring 任務被調度執行的時間。 end_timestring 任務結束時間。 resultsarray[object] 每個待識別音頻檔案對應的子任務結果清單。 屬性 subtask_statusstring 子任務狀態。 file_urlstring 檔案轉寫任務中所處理的檔案URL。 transcription_urlstring 擷取識別結果對應的連結。該連結有效期間為24小時,逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。 識別結果儲存為JSON檔案,您可以通過上述連結下載該檔案或直接通過HTTP請求讀取該檔案中的內容。JSON資料中各欄位含義請參見識別結果說明。 codestring 子任務失敗的錯誤碼。 messagestring 子任務失敗的錯誤資訊。 task_metricsobject 任務整體執行情況統計。 屬性 TOTALinteger 子任務總數。 SUCCEEDEDinteger 成功的子任務數。 FAILEDinteger 失敗的子任務數。 | {
"request_id": "f9e1afad-94d3-997e-a83b-************",
"output": {
"task_id": "f86ec806-4d73-485f-a24f-************",
"task_status": "SUCCEEDED",
"submit_time": "2024-09-12 15:11:40.041",
"scheduled_time": "2024-09-12 15:11:40.071",
"end_time": "2024-09-12 15:11:40.903",
"results": [
{
"file_url": "{YOUR_AUDIO_URL}",
"transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
"subtask_status": "SUCCEEDED"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"duration": 9
}
}
{
"task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2024-12-16 16:30:59.170",
"scheduled_time": "2024-12-16 16:30:59.204",
"end_time": "2024-12-16 16:31:02.375",
"results": [
{
"file_url": "{YOUR_AUDIO_URL}",
"code": "FILE_DOWNLOAD_FAILED",
"message": "FILE_DOWNLOAD_FAILED",
"subtask_status": "FAILED"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 0,
"FAILED": 1
}
}
|
其他介面:批量查詢任務狀態/取消任務
詳情請參見管理非同步任務:支援批量查詢24小時內提交的非即時語音辨識任務,同時支援取消PENDING(排隊)狀態的任務。
識別結果說明
識別結果儲存為JSON檔案。
{
"file_url":"{YOUR_AUDIO_URL}",
"properties":{
"audio_format":"pcm_s16le",
"channels":[
0
],
"original_sampling_rate":16000,
"original_duration_in_milliseconds":3834
},
"transcripts":[
{
"channel_id":0,
"content_duration_in_milliseconds":3720,
"text":"Hello world, 這裡是阿里巴巴語音實驗室。",
"sentences":[
{
"begin_time":100,
"end_time":3820,
"text":"Hello world, 這裡是阿里巴巴語音實驗室。",
"sentence_id":1,
"speaker_id":0, //當開啟自動說話人分離功能時才會顯示該欄位
"words":[
{
"begin_time":100,
"end_time":596,
"text":"Hello ",
"punctuation":""
},
{
"begin_time":596,
"end_time":844,
"text":"world",
"punctuation":", "
}
// 這裡省略其它內容
]
}
]
}
]
}
需要關注的參數如下:
| 參數 | 類型 | 說明 |
|---|
audio_format
| string
| 源檔案中音訊格式。 |
channels
| array[integer] | 源檔案中音訊音軌索引資訊,對單軌音頻返回[0],對雙軌音頻返回[0, 1],以此類推。 |
original_sampling_rate
| integer
| 源檔案中音訊採樣率(Hz)。 |
original_duration_in_milliseconds
| integer
| 源檔案中的原始音頻時間長度(ms)。 |
channel_id
| integer
| 轉寫結果的音軌索引,以0為起始。 |
content_duration
| integer
| 音軌中被判定為語音內容的時間長度(ms)。 說明以下計費說明適用於 qwen-audio-3.0-asr-flash-filetrans。qwen-audio-3.1-asr-flash-filetrans 按 Token 計費。 語音辨識模型服務僅對音軌中被判定為語音內容的時間長度進行語音轉寫,並據此進行計量計費,非語音內容不計量、不計費。通常情況下語音內容時間長度會短於原始音頻時間長度。由於對是否存在語音內容的判定是由AI模型給出的,可能與實際情況存在一定誤差。 |
transcript
| string
| 段落層級的語音轉寫結果。 |
sentences
| array
| 句子層級的語音轉寫結果。 |
words
| array
| 詞層級的語音轉寫結果。 |
begin_time
| integer
| 開始時間戳(ms)。 |
end_time
| integer
| 結束時間戳記(ms)。 |
text
| string
| 語音轉寫結果。 |
speaker_id
| integer
| 當前說話人的索引,以0為起始,用於區分不同的說話人。 僅在啟用說話人分離功能時,該欄位才會顯示於識別結果中。 |
punctuation
| string
| 預測出的詞之後的標點符號(如有)。 |