本文介紹FunAudio-ASR錄音檔案識別RESTful API的參數和介面細節。
使用者指南：關於模型介紹和選型建議請參見錄音檔案識別-Fun-ASR/Paraformer/SenseVoice。
目前提供了提交任務介面和查詢任務介面，通常情況下，您可以先調用提交任務介面上傳識別任務，然後迴圈調用查詢任務介面，直至任務完成。
前提條件
已開通服務並擷取API Key。請配置API Key到環境變數，而非寫入程式碼在代碼中，防範因代碼泄露導致的安全風險。
當您需要為第三方應用或使用者提供臨時存取權限，或者希望嚴格控制敏感性資料訪問、刪除等高風險操作時，建議使用臨時鑒權Token。
與長期有效 API Key 相比，臨時鑒權 Token 具備時效性短（60秒）、安全性高的特點，適用於臨時調用情境，能有效降低API Key泄露的風險。
使用方式：在代碼中，將原本用於鑒權的 API Key 替換為擷取到的臨時鑒權 Token 即可。
模型列表
國際
服務部署範圍為國際時，模型推理計算資源在全球範圍內動態調度（不含中國內地）；待用資料儲存於您所選的地區。該部署範圍支援的地區：新加坡。
模型名稱 | 版本 | 單價 | 免費額度（注） |
fun-asr 當前等同fun-asr-2025-11-07 | 穩定版 | $0.000035/秒 | 36,000秒（10小時） 有效期間90天 |
fun-asr-2025-11-07 相較fun-asr-2025-08-25做了遠場VAD最佳化，識別更准 | 快照版 | ||
fun-asr-2025-08-25 | |||
fun-asr-mtl 當前等同fun-asr-mtl-2025-08-25 | 穩定版 | ||
fun-asr-mtl-2025-08-25 | 快照版 |
支援的語種：
fun-asr、fun-asr-2025-11-07：中文（普通話、粵語、吳語、閩南語、客家話、贛語、湘語、晉語；並支援中原、西南、冀魯、江淮、蘭銀、膠遼、東北、北京、港台等，包括河南、陝西、湖北、四川、重慶、雲南、貴州、廣東、廣西、河北、天津、山東、安徽、南京、江蘇、杭州、甘肅、寧夏等地區官話口音）、英文、日語
fun-asr-2025-08-25：中文（普通話）、英文
fun-asr-mtl、fun-asr-mtl-2025-08-25：中文（普通話、粵語）、英文、日語、韓語、越南語、印尼語、泰語、馬來語、菲律賓語、阿拉伯語、印地語、保加利亞語、克羅地亞語、捷克語、丹麥語、荷蘭語、愛沙尼亞語、芬蘭語、希臘語、匈牙利語、愛爾蘭語、拉脫維亞語、立陶宛語、馬爾他語、波蘭語、葡萄牙語、羅馬尼亞語、斯洛伐克語、斯洛文尼亞語、瑞典語
支援的採樣率：任意
支援的音頻格式：aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv
中國內地
服務部署範圍為中國內地時，模型推理計算資源僅限於中國內地；待用資料儲存於您所選的地區。該部署範圍支援的地區：華北2（北京）。
模型名稱 | 版本 | 單價 | 免費額度（注） |
fun-asr 當前等同fun-asr-2025-11-07 | 穩定版 | $0.000032/秒 | 無免費額度 |
fun-asr-2025-11-07 相較fun-asr-2025-08-25做了遠場VAD最佳化，識別更准 | 快照版 | ||
fun-asr-2025-08-25 | |||
fun-asr-mtl 當前等同fun-asr-mtl-2025-08-25 | 穩定版 | ||
fun-asr-mtl-2025-08-25 | 快照版 |
支援的語種：
fun-asr、fun-asr-2025-11-07：中文（普通話、粵語、吳語、閩南語、客家話、贛語、湘語、晉語；並支援中原、西南、冀魯、江淮、蘭銀、膠遼、東北、北京、港台等，包括河南、陝西、湖北、四川、重慶、雲南、貴州、廣東、廣西、河北、天津、山東、安徽、南京、江蘇、杭州、甘肅、寧夏等地區官話口音）、英文、日語
fun-asr-2025-08-25：中文（普通話）、英文
fun-asr-mtl、fun-asr-mtl-2025-08-25：中文（普通話、粵語）、英文、日語、韓語、越南語、印尼語、泰語、馬來語、菲律賓語、阿拉伯語、印地語、保加利亞語、克羅地亞語、捷克語、丹麥語、荷蘭語、愛沙尼亞語、芬蘭語、希臘語、匈牙利語、愛爾蘭語、拉脫維亞語、立陶宛語、馬爾他語、波蘭語、葡萄牙語、羅馬尼亞語、斯洛伐克語、斯洛文尼亞語、瑞典語
支援的採樣率：任意
支援的音頻格式：aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv
約束
服務不支援本地音視頻檔案直傳（也不支援base64格式音頻），輸入源需為可通過公網訪問的檔案URL（支援HTTP/HTTPS協議，樣本：https://your-domain.com/file.mp3）。
使用SDK時，若錄音檔案儲存體在阿里雲OSS，不支援使用以 oss://為首碼的臨時 URL。
使用RESTful API時，若錄音檔案儲存體在阿里雲OSS，支援使用以 oss://為首碼的臨時 URL：
臨時 URL 有效期間48小時，到期後無法使用，請勿用於生產環境。
檔案上傳憑證介面限流為 100 QPS 且不支援擴容，請勿用於生產環境、高並發及壓測情境。
生產環境建議使用阿里雲OSS 等穩定儲存，確保檔案長期可用並規避限流問題。
URL通過file_urls參數指定，單次請求最多支援100個URL。
-
音頻格式
aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv重要由於音視頻格式及其變種眾多，技術上無法窮盡測試，API不能保證所有格式均能夠被正確識別。請通過測實驗證您所提供的檔案能夠獲得正常的語音辨識結果。
-
音頻採樣率：任意
-
音頻檔案大小和時間長度
音頻檔案不超過2GB；時間長度在12小時以內。
如果希望處理的檔案超過了上述限制，可嘗試對檔案進行預先處理以降低檔案尺寸。有關檔案預先處理的最佳實務可以查閱預先處理視頻檔案以提高檔案轉寫效率（針對錄音檔案識別情境）。
-
批處理音頻數目
單次請求最多支援100個檔案URL。
-
可識別語言：fun-asr 支援中文、英文；fun-asr-mtl-2025-08-25 支援中文、粵語、英文、日語、泰語、越南語、印尼語。
-
介面調用方式限制
不支援前端直接調用API，需通過後端中轉。
提交任務介面
基本資料
|
介面描述 |
提交語音辨識任務。 |
|
URL |
以下為新加坡地區url，若使用北京地區的模型，需將url替換為： |
|
要求方法 |
POST |
|
要求標頭 |
|
|
訊息體 |
包含所有請求參數的訊息體如下，對於可選欄位，在實際業務中可根據需求省略： |
請求參數
|
參數 |
類型 |
預設值 |
是否必須 |
說明 |
|
model |
string |
- |
是 |
指定用於音視頻檔案轉寫的模型名。參見模型列表。 |
|
file_urls |
array[string] |
- |
是 |
音視頻檔案轉寫的URL列表，支援HTTP / HTTPS協議，單次請求最多支援100個URL。 若錄音檔案儲存體在阿里雲OSS，使用RESTful API方式支援使用以 oss://為首碼的臨時 URL。 重要
|
|
vocabulary_id |
string |
- |
否 |
熱詞ID，此次語音辨識中生效此熱詞ID對應的熱詞資訊。預設不啟用。使用方法請參考定製熱詞。 |
|
channel_id |
array[integer] |
[0] |
否 |
指定在多音軌音頻檔案中需要識別的音軌索引，索引從 0 開始。例如，[0] 表示識別第一個音軌，[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數，則預設處理第一個音軌。 重要
指定的每一個音軌都將獨立計費。例如，為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。 |
|
special_word_filter |
string |
- |
否 |
指定在語音辨識過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。 若未傳入該參數，系統將啟用系統內建的敏感詞過濾邏輯，識別結果中與阿里雲百鍊敏感詞表匹配的詞語將被替換為等長的 若傳入該參數，則可實現以下敏感詞處理策略：
該參數的值應為一個 JSON 字串，其結構如下所示： JSON欄位說明：
|
|
diarization_enabled |
boolean |
false |
否 |
自動說話人分離，預設關閉。 僅適用於單聲道音頻，多頻道音訊不支援說話人分離。 啟用該功能後，識別結果中將顯示 有關 |
|
speaker_count |
integer |
- |
否 |
說話人數量參考值。取值範圍為2至100的整數（包含2和100）。 開啟說話人分離功能後（diarization_enabled設定為true）生效。 預設自動判斷說話人數量，如果配置此項，只能輔助演算法盡量輸出指定人數，無法保證一定會輸出此人數。 |
|
language_hints |
array[string] |
- |
否 |
設定待識別語言代碼。如果無法提前確定語種，可不設定，模型會自動識別語種。 不同模型支援的語言代碼如下：
|
響應參數
|
參數 |
類型 |
說明 |
|
task_status |
string |
任務狀態。 |
|
task_id |
string |
查詢任務介面
基本資料
|
介面描述 |
查詢語音辨識任務執行情況和結果。 |
|
URL |
以下為新加坡地區url，若使用北京地區的模型，需將url替換為： |
|
要求方法 |
POST |
|
要求標頭 |
|
|
訊息體 |
無。 |
請求參數
|
參數 |
類型 |
預設值 |
是否必須 |
說明 |
|
task_id |
string |
- |
是 |
查詢任務需指定其ID，該ID為提交任務介面被調用後返回的 |
響應參數
|
參數 |
類型 |
說明 |
|
task_id |
string |
被查詢任務的ID。 |
|
task_status |
string |
被查詢任務的狀態。 說明
當任務包含多個子任務時，只要存在任一子任務成功，整個任務狀態將標記為 |
|
subtask_status |
string |
子任務狀態。 |
|
file_url |
string |
檔案轉寫任務中所處理的檔案URL。 |
|
transcription_url |
string |
擷取識別結果對應的連結。該連結有效期間為24小時，逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。 識別結果儲存為JSON檔案，您可以通過上述連結下載該檔案或直接通過HTTP請求讀取該檔案中的內容。 JSON資料中各欄位含義請參見識別結果說明。 |
識別結果說明
識別結果儲存為JSON檔案。
需要關注的參數如下：
|
參數 |
類型 |
說明 |
|
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_in_milliseconds |
integer |
音軌中被判定為語音內容的時間長度（ms）。 重要
語音辨識模型服務僅對音軌中被判定為語音內容的時間長度進行語音轉寫，並據此進行計量計費，非語音內容不計量、不計費。通常情況下語音內容時間長度會短於原始音頻時間長度。由於對是否存在語音內容的判定是由AI模型給出的，可能與實際情況存在一定誤差。 |
|
transcripts |
string |
段落層級的語音轉寫結果。 |
|
sentences |
array |
句子層級的語音轉寫結果。 |
|
words |
array |
詞層級的語音轉寫結果。 |
|
begin_time |
integer |
開始時間戳（ms）。 |
|
end_time |
integer |
結束時間戳記（ms）。 |
|
text |
string |
語音轉寫結果。 |
|
speaker_id |
integer |
當前說話人的索引，以0為起始，用於區分不同的說話人。 僅在啟用說話人分離功能時，該欄位才會顯示於識別結果中。 |
|
punctuation |
string |
預測出的詞之後的標點符號（如有）。 |
完整樣本
您可以使用程式設計語言內建的HTTP類庫，來實現提交和查詢任務的請求：先調用提交任務介面上傳識別任務，然後迴圈調用查詢任務介面，直至任務完成。
以Python為例，代碼如下：
import requests
import json
import os
import time
# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：api_key = "sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
file_urls = [
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
]
# 新加坡地區和北京地區的Region不同。若使用北京地區，需將下面這行替換為：region = "dashscope.aliyuncs.com"
region = "dashscope-intl.aliyuncs.com"
# 提交檔案轉寫任務，包含待轉寫檔案url列表
def submit_task(apikey, file_urls) -> str:
headers = {
"Authorization": f"Bearer {apikey}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
}
data = {
"model": "fun-asr",
"input": {"file_urls": file_urls},
"parameters": {
"channel_id": [0]
},
}
# 錄音檔案轉寫服務url
service_url = (
f"https://{region}/api/v1/services/audio/asr/transcription"
)
response = requests.post(
service_url, headers=headers, data=json.dumps(data)
)
# 列印響應內容
if response.status_code == 200:
return response.json()["output"]["task_id"]
else:
print("task failed!")
print(response.json())
return None
# 迴圈查詢任務狀態直到成功
def wait_for_complete(task_id):
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
}
pending = True
while pending:
# 查詢任務狀態服務url
service_url = f"https://{region}/api/v1/tasks/{task_id}"
response = requests.post(
service_url, headers=headers
)
if response.status_code == 200:
status = response.json()['output']['task_status']
if status == 'SUCCEEDED':
print("task succeeded!")
pending = False
return response.json()['output']['results']
elif status == 'RUNNING' or status == 'PENDING':
pass
else:
print("task failed!")
pending = False
else:
print("query failed!")
pending = False
print(response.json())
time.sleep(0.1)
task_id = submit_task(apikey=api_key, file_urls=file_urls)
print("task_id: ", task_id)
result = wait_for_complete(task_id)
print("transcription result: ", result)錯誤碼
如遇報錯問題，請參見錯誤資訊進行排查。
當任務包含多個子任務時，只要存在任一子任務成功，整個任務狀態將標記為SUCCEEDED，需通過subtask_status欄位判斷具體子任務結果。
錯誤返回樣本：
{
"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": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
"transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20241216/xxxx",
"subtask_status": "SUCCEEDED"
},
{
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_exaple_1.wav",
"code": "InvalidFile.DownloadFailed",
"message": "The audio file cannot be downloaded.",
"subtask_status": "FAILED"
}
],
"task_metrics": {
"TOTAL": 2,
"SUCCEEDED": 1,
"FAILED": 1
}
}常見問題
功能特性
Q：是否支援Base64編碼方式的音頻？
不支援Base64編碼方式的音頻。僅支援可通過公網訪問的 URL 所指向的音訊識別，不支援識別二進位流，也不支援直接識別本地檔案。
Q：如何將音頻檔案以公網可訪問的URL形式提供？
通常遵循以下幾個步驟（這裡為您提供一種思路，具體情況因不同儲存產品而異，推薦將音頻上傳至阿里雲OSS）：
使用SDK時，若錄音檔案儲存體在阿里雲OSS，不支援使用以 oss://為首碼的臨時 URL。
使用RESTful API時，若錄音檔案儲存體在阿里雲OSS，支援使用以 oss://為首碼的臨時 URL：
臨時 URL 有效期間48小時，到期後無法使用，請勿用於生產環境。
檔案上傳憑證介面限流為 100 QPS 且不支援擴容，請勿用於生產環境、高並發及壓測情境。
生產環境建議使用阿里雲OSS 等穩定儲存，確保檔案長期可用並規避限流問題。
Q：多久能擷取識別結果？
任務提交後將進入排隊（PENDING）狀態，排隊時間取決於隊列長度和檔案時間長度，無法明確給出，通常在數分鐘內，請耐心等待。並且音頻時間長度越長，所需時間越久。
故障排查
如遇代碼報錯問題，請根據錯誤碼中的資訊進行排查。
Q：錄音檔案URL設定成OSS臨時公網訪問不通該如何處理？
headers中將X-DashScope-OssResourceResolve設為enable。
不推薦該方式。
Java SDK或者Python SDK不支援對headers進行配置。
Q：一直輪詢不到結果？
可能是限流原因，請耐心等待。
Q：無法識別語音（無識別結果）是什麼原因？
請檢查音頻格式和採樣率是否正確且符合參數約束。
可以使用ffprobe工具擷取音訊容器、編碼、採樣率、聲道等資訊：
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx