使用Python SDK非同步呼叫Fun-ASR識別錄音檔案-大模型服務平台百鍊-阿里雲

本文介紹Fun-ASR錄音檔案識別Python SDK的參數和介面細節。

使用者指南：關於模型介紹和選型建議請參見錄音檔案識別-Fun-ASR/Paraformer/SenseVoice。

前提條件

已開通服務並擷取API Key。請配置API Key到環境變數（準備下線，併入配置 API Key），而非寫入程式碼在代碼中，防範因代碼泄露導致的安全風險。
說明
當您需要為第三方應用或使用者提供臨時存取權限，或者希望嚴格控制敏感性資料訪問、刪除等高風險操作時，建議使用臨時鑒權Token。
與長期有效 API Key 相比，臨時鑒權 Token 具備時效性短（60秒）、安全性高的特點，適用於臨時調用情境，能有效降低API Key泄露的風險。
使用方式：在代碼中，將原本用於鑒權的 API Key 替換為擷取到的臨時鑒權 Token 即可。
安裝最新版DashScope SDK。

模型列表

國際

在國際部署模式下，存取點與資料存放區均位於新加坡地區，模型推理計算資源在全球範圍內動態調度（不含中國內地）。

模型名稱	版本	單價	免費額度（注）
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

中國內地

在中國內地部署模式下，存取點與資料存放區均位於北京地區，模型推理計算資源僅限於中國內地。

模型名稱	版本	單價	免費額度（注）
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 支援中文，粵語、英文、日語、泰語、越南語、印尼語。

快速開始

核心類（Transcription）提供了非同步提交任務、同步等待任務結束和非同步查詢任務執行結果的介面。可通過如下兩種調用方式進行錄音檔案識別：

非同步提交任務+同步等待任務結束：提交任務後，阻塞當前線程直到任務結束並擷取識別結果。
非同步提交任務+非同步查詢任務執行結果：提交任務後，在需要的時候通過調用查詢任務介面擷取任務的執行結果。

非同步提交任務+同步等待任務結束

調用核心類（Transcription）的async_call方法並設定請求參數。
說明
- 檔案轉寫服務對通過API提交的任務採取儘力服務原則進行處理。任務提交後將進入排隊（PENDING）狀態，排隊時間取決於隊列長度和檔案時間長度，無法明確給出，通常在數分鐘內。任務開始處理後，語音辨識將以數百倍加速完成。
- 每一個任務完成後，識別結果和URL下載連結有效期間為24小時，逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。
調用核心類（Transcription）的wait方法同步等待任務結束。
任務的狀態包括PENDING、RUNNING、SUCCEEDED和FAILED。當任務處於PENDING或RUNNING狀態時，wait介面將被阻塞。當任務處於SUCCEEDED或FAILED狀態時，wait介面不再阻塞並返回任務的執行結果。
wait返回TranscriptionResponse。

點擊查看完整樣本

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import dashscope
import os
import json

# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

task_response = Transcription.async_call(
    model='fun-asr',
    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']
)

transcribe_response = Transcription.wait(task=task_response.output.task_id)
if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('transcription done!')

非同步提交任務+非同步查詢任務執行結果

調用核心類（Transcription）的async_call方法並設定請求參數。
說明
- 檔案轉寫服務對通過API提交的任務採取儘力服務原則進行處理。任務提交後將進入排隊（PENDING）狀態，排隊時間取決於隊列長度和檔案時間長度，無法明確給出，通常在數分鐘內。任務開始處理後，語音辨識將以數百倍加速完成。
- 每一個任務完成後，識別結果和URL下載連結有效期間為24小時，逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。
迴圈調用核心類（Transcription）的fetch方法直到擷取最終的任務結果。
當任務狀態為SUCCEEDED或FAILED時，停止輪詢並處理結果。
fetch返回TranscriptionResponse。

點擊查看完整樣本

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import dashscope
import os
import json

# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

transcribe_response = Transcription.async_call(
    model='fun-asr',
    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']
)

while True:
    if transcribe_response.output.task_status == 'SUCCEEDED' or transcribe_response.output.task_status == 'FAILED':
        break
    transcribe_response = Transcription.fetch(task=transcribe_response.output.task_id)

if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('transcription done!')

請求參數

請求參數通過核心類（Transcription）的async_call方法進行設定。

參數	類型	預設值	是否必須	說明
model	str	-	是	指定用於音視頻檔案轉寫的模型名。參見模型列表。
file_urls	list[str]	-	是	音視頻檔案轉寫的URL列表，支援HTTP / HTTPS協議，單次請求最多支援100個URL。若錄音檔案儲存體在阿里雲OSS，使用SDK方式不支援使用以 oss://為首碼的臨時 URL。
channel_id	list[int]	[0]	否	指定在多音軌音頻檔案中需要識別的音軌索引，索引從 0 開始。例如，[0] 表示識別第一個音軌，[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數，則預設處理第一個音軌。重要指定的每一個音軌都將獨立計費。例如，為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。
special_word_filter	str	-	否	指定在語音辨識過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。若未傳入該參數，系統將啟用系統內建的敏感詞過濾邏輯，識別結果中與阿里雲百鍊敏感詞表匹配的詞語將被替換為等長的``。若傳入該參數，則可實現以下敏感詞處理策略：替換為 ``：將匹配的敏感詞替換為等長的 ``；直接過濾：將匹配的敏感詞從識別結果中完全移除。該參數的值應為一個 JSON 字串，其結構如下所示： `{ "filter_with_signed": { "word_list": ["測試"] }, "filter_with_empty": { "word_list": ["開始", "發生"] }, "system_reserved_filter": true }` JSON欄位說明： `filter_with_signed` 類型：對象。是否必填：否。描述：配置需替換為``的敏感詞列表。識別結果中匹配的詞語將被等長的 `` 替代。樣本：以上述JSON為例，“幫我測試一下這段代碼”的語音辨識結果將會是“幫我一下這段代碼”。內部欄位： `word_list`: 字串數組，列出需被替換的敏感詞。 `filter_with_empty` 類型：對象。是否必填：否。描述：配置需從識別結果中移除（過濾）的敏感詞列表。識別結果中匹配的詞語將被完全刪除。樣本：以上述JSON為例，“比賽這就要開始了嗎？”的語音辨識結果將會是“比賽這就要了嗎”。內部欄位： `word_list`: 字串數組，列出需被完全移除（過濾）的敏感詞。 `system_reserved_filter` 類型：布爾值。是否必填：否。預設值：true。描述：是否啟用系統預置的敏感詞規則。設為`true`時，將同時啟用系統內建的敏感詞過濾邏輯，識別結果中與阿里雲百鍊敏感詞表匹配的詞語將被替換為等長的``。
diarization_enabled	bool	False	否	自動說話人分離，預設關閉。僅適用於單聲道音頻，多頻道音訊不支援說話人分離。啟用該功能後，識別結果中將顯示`speaker_id`欄位，用於區分不同說話人。有關`speaker_id`的樣本，請參見識別結果說明。
speaker_count	int	-	否	說話人數量參考值。取值範圍為2至100的整數（包含2和100）。開啟說話人分離功能後（`diarization_enabled`設定為true）生效。預設自動判斷說話人數量，如果配置此項，只能輔助演算法盡量輸出指定人數，無法保證一定會輸出此人數。
language_hints	list[str]	-	否	設定待識別語言代碼。如果無法提前確定語種，可不設定，模型會自動識別語種。系統僅讀取數組中的首個值。多餘值將被忽略。不同模型支援的語言代碼如下： fun-asr、fun-asr-2025-11-07： zh: 中文 en: 英文 ja: 日語 fun-asr-2025-08-25： zh: 中文 en: 英文 fun-asr-mtl、fun-asr-mtl-2025-08-25： zh: 中文 en: 英文 ja: 日語 ko：韓語 vi：越南語 id：印尼語 th：泰語 ms：馬來語 tl：菲律賓語 ar：阿拉伯語 hi：印地語 bg：保加利亞語 hr：克羅地亞語 cs：捷克語 da：丹麥語 nl：荷蘭語 et：愛沙尼亞語 fi：芬蘭語 el：希臘語 hu：匈牙利語 ga：愛爾蘭語 lv：拉脫維亞語 lt：立陶宛語 mt：馬爾他語 pl：波蘭語 pt：葡萄牙語 ro：羅馬尼亞語 sk：斯洛伐克語 sl：斯洛文尼亞語 sv：瑞典語

響應結果

`TranscriptionResponse`

TranscriptionResponse封裝了任務的基本資料（task_id和task_status）和執行結果（output屬性對應的內容，參見TranscriptionOutput）。

點擊查看TranscriptionResponse結構樣本

`PENDING`狀態

{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING",
        "submit_time":"2025-02-13 16:55:08.573",
        "scheduled_time":"2025-02-13 16:55:08.592",
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":0,
            "FAILED":0
        }
    },
    "usage":null
}

`RUNNING`狀態

{
    "status_code":200,
    "request_id":"d9d530f1-853c-9848-a5f1-f5de59086ff7",
    "code":null,
    "message":"",
    "output":{
        "task_id":"6351feef-9694-45d2-9d32-63454f2ffb8d",
        "task_status":"RUNNING",
        "submit_time":"2025-02-13 17:31:20.681",
        "scheduled_time":"2025-02-13 17:31:20.703",
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":1,
            "FAILED":0
        }
    },
    "usage":null
}

`SUCCEEDED`狀態

{
    "status_code":200,
    "request_id":"16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code":null,
    "message":"",
    "output":{
        "task_id":"6351feef-9694-45d2-9d32-63454f2ffb8d",
        "task_status":"SUCCEEDED",
        "submit_time":"2025-02-13 17:31:20.681",
        "scheduled_time":"2025-02-13 17:31:20.703",
        "end_time":"2025-02-13 17:31:21.867",
        "results":[
            {
                "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
                "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A31/20ee4e4f-0404-4806-b617-c7d4c62eed19-1.json?Expires=1739525481&OSSAccessKeyId=yourOSSAccessKeyId&Signature=3q%2B1uQmRwltd7FPn5HQM2mBKw74%3D",
                "subtask_status":"SUCCEEDED"
            },
            {
                "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
                "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A31/be4f14c5-e46b-47ff-b03a-476ae9a45fd3-1.json?Expires=1739525481&OSSAccessKeyId=yourOSSAccessKeyId&Signature=EUX%2FRkGcn46L5d93ihQmpWUeYE4%3D",
                "subtask_status":"SUCCEEDED"
            }
        ],
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":2,
            "FAILED":0
        }
    },
    "usage":{
        "duration":9
    }
}

`FAILED`狀態

{
    "status_code":200,
    "request_id":"16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code":null,
    "message":"",
    "output":{
        "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
        }
    },
    "usage":{
        "duration":9
    }
}

需要關注的參數：

參數	說明
status_code	HTTP請求狀態代碼。
code	最外層的`code`不必關注。 `output.results`下面的`code`，代表錯誤碼。可以結合`message`欄位，對照錯誤碼排查問題。
message	最外層的`message`不必關注。 `output.results`下面的`message`，代表錯誤資訊。可以結合`code`欄位，對照錯誤碼排查問題。
task_id	任務ID。
task_status	任務狀態。有`PENDING`、`RUNNING`、`SUCCEEDED`和`FAILED`這四種狀態。當任務包含多個子任務時，只要存在任一子任務成功，整個任務狀態將標記為`SUCCEEDED`，需通過`subtask_status`欄位判斷具體子任務結果。
results	子任務識別結果。
subtask_status	子任務狀態。有`PENDING`、`RUNNING`、`SUCCEEDED`和`FAILED`這四種狀態。
file_url	被識別音訊URL。
transcription_url	音頻識別結果對應的URL。識別結果儲存為JSON檔案，您可以通過`transcription_url`對應的連結下載檔案或直接通過HTTP請求讀取該檔案中的內容。JSON檔案的內容請參見識別結果說明。

`TranscriptionOutput`

TranscriptionOutput對應TranscriptionResponse的output屬性，代表當前任務執行結果。

點擊查看TranscriptionOutput結構樣本

PENDING狀態

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"PENDING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":2,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

RUNNING狀態

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"RUNNING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":2,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

`SUCCEEDED`狀態

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"SUCCEEDED",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "end_time":"2025-02-13 17:59:28.828",
    "results":[
        {
            "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
            "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A59/70e737cc-bf8c-418b-b0c8-83fab192a0fa-1.json?Expires=1739527168&OSSAccessKeyId=yourOSSAccessKeyId&Signature=AtGjIKI%2BdgbzjJIu%2BHsr1R5nSAY%3D",
            "subtask_status":"SUCCEEDED"
        },
        {
            "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
            "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A59/ce1ebe74-be78-4ac8-b4f8-8e438a14d1c2-1.json?Expires=1739527168&OSSAccessKeyId=yourOSSAccessKeyId&Signature=z5s0ROpSU8HwiM8WHPNVpkuFG3A%3D",
            "subtask_status":"SUCCEEDED"
        }
    ],
    "task_metrics":{
        "TOTAL":2,
        "SUCCEEDED":2,
        "FAILED":0
    }
}

`FAILED`狀態

“code”為錯誤碼，“message”為錯誤資訊，只有異常情況才有這兩個欄位，您可以通過這兩個欄位，對照錯誤碼排查問題。

{
    "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
    }
}

需要關注的參數：

參數	說明
code	代表錯誤碼。可以結合`message`欄位，對照錯誤碼排查問題。
message	代表錯誤資訊。可以結合`code`欄位，對照錯誤碼排查問題。
task_id	任務ID。
task_status	任務狀態。有`PENDING`、`RUNNING`、`SUCCEEDED`和`FAILED`這四種狀態。當任務包含多個子任務時，只要存在任一子任務成功，整個任務狀態將標記為`SUCCEEDED`，需通過`subtask_status`欄位判斷具體子任務結果。
results	子任務識別結果。
subtask_status	子任務狀態。有`PENDING`、`RUNNING`、`SUCCEEDED`和`FAILED`這四種狀態。
file_url	被識別音訊URL。
transcription_url	音頻識別結果對應的URL。識別結果以JSON格式儲存在一個JSON檔案中，您可以通過`transcription_url`對應的連結下載檔案或直接通過HTTP請求讀取該檔案中的內容。JSON檔案的內容請參見識別結果說明。

識別結果說明

識別結果儲存為JSON檔案。

點擊查看識別結果樣本

{
    "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
    "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）。重要語音辨識模型服務僅對音軌中被判定為語音內容的時間長度進行語音轉寫，並據此進行計量計費，非語音內容不計量、不計費。通常情況下語音內容時間長度會短於原始音頻時間長度。由於對是否存在語音內容的判定是由AI模型給出的，可能與實際情況存在一定誤差。
transcript	string	段落層級的語音轉寫結果。
sentences	array	句子層級的語音轉寫結果。
words	array	詞層級的語音轉寫結果。
begin_time	integer	開始時間戳（ms）。
end_time	integer	結束時間戳記（ms）。
text	string	語音轉寫結果。
speaker_id	integer	當前說話人的索引，以0為起始，用於區分不同的說話人。僅在啟用說話人分離功能時，該欄位才會顯示於識別結果中。
punctuation	string	預測出的詞之後的標點符號（如有）。

關鍵介面

核心類（`Transcription`）

Transcription可以通過“from dashscope.audio.asr import Transcription”方式引入。

成員方法	方法簽名	說明
async_call	`@classmethod def async_call(cls, model: str, file_urls: List[str], phrase_id: str = None, api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	非同步提交語音辨識任務。
wait	`@classmethod def wait(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	阻塞當前線程直到非同步任務結束（任務狀態為`SUCCEEDED`或`FAILED`）。該方法返回TranscriptionResponse。
fetch	`@classmethod def fetch(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	非同步查詢當前任務執行結果。該方法返回TranscriptionResponse。

錯誤碼

如遇報錯問題，請參見錯誤資訊進行排查。

當任務包含多個子任務時，只要存在任一子任務成功，整個任務狀態將標記為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）：

1、選擇儲存和託管方式

如以下這幾種：

Object Storage Service服務（推薦）：
- 使用雲端服務商的Object Storage Service服務（如阿里雲OSS），將音頻檔案上傳到儲存桶中，並設定為公開訪問。
- 優點：高可用性、支援 CDN 加速、易於管理。
Web 服務器：
- 將音頻檔案放置在支援 HTTP/HTTPS 訪問的 Web 服務器上（如 Nginx、Apache）。
- 優點：適合小型專案或本地測試。
內容分發網路（CDN）：
- 將音頻檔案託管在 CDN 上，通過 CDN 提供的 URL 訪問。
- 優點：加速檔案傳輸，適合高並發情境。

2、上傳音頻檔案

根據選擇的儲存/託管方式，將音頻上傳，如：

Object Storage Service服務：
- 登入雲端服務商的控制台，建立儲存桶。
- 上傳音頻檔案，並設定檔案許可權為“公用讀取”或產生臨時訪問連結。
Web 服務器：
- 將音頻檔案放置在伺服器指定目錄下（如 /var/www/html/audio/）。
- 確保檔案可以通過 HTTP/HTTPS 訪問。

3、產生公網可訪問的URL

例如：

Object Storage Service服務：
- 檔案上傳後，系統會自動產生一個公網存取 URL（通常格式為 https://<bucket-name>.<region>.aliyuncs.com/<file-name>）。
- 如果需要更友好的網域名稱，可以綁定自訂網域名並開啟 HTTPS。
Web 服務器：
- 檔案的存取 URL 通常是伺服器位址加上檔案路徑（如 https://your-domain.com/audio/file.mp3）。
CDN：
- 配置 CDN 加速後，使用 CDN 提供的 URL（如 https://cdn.your-domain.com/audio/file.mp3）。

4、驗證URL的可用性

公網環境下，確保產生的 URL 可以正常訪問，例如：

在瀏覽器中開啟 URL，檢查是否能播放音頻檔案。
使用工具（如 curl 或 Postman）驗證 URL 是否返回正確的 HTTP 響應（狀態代碼 200）。

使用SDK時，若錄音檔案儲存體在阿里雲OSS，不支援使用以 oss://為首碼的臨時 URL。

使用RESTful API時，若錄音檔案儲存體在阿里雲OSS，支援使用以 oss://為首碼的臨時 URL：

重要

臨時 URL 有效期間48小時，到期後無法使用，請勿用於生產環境。
檔案上傳憑證介面限流為 100 QPS 且不支援擴容，請勿用於生產環境、高並發及壓測情境。
生產環境建議使用阿里雲OSS 等穩定儲存，確保檔案長期可用並規避限流問題。

Q：多久能擷取識別結果？

任務提交後將進入排隊（PENDING）狀態，排隊時間取決於隊列長度和檔案時間長度，無法明確給出，通常在數分鐘內，請耐心等待。並且音頻時間長度越長，所需時間越久。

故障排查

如遇代碼報錯問題，請根據錯誤碼中的資訊進行排查。

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

前提條件

模型列表

國際

中國內地

約束

快速開始

非同步提交任務+同步等待任務結束

非同步提交任務+非同步查詢任務執行結果

請求參數

響應結果

TranscriptionResponse

PENDING狀態

RUNNING狀態

SUCCEEDED狀態

FAILED狀態

TranscriptionOutput

PENDING狀態

RUNNING狀態

SUCCEEDED狀態

FAILED狀態

識別結果說明

關鍵介面

核心類（Transcription）

錯誤碼

常見問題

功能特性

Q：是否支援Base64編碼方式的音頻？

Q：如何將音頻檔案以公網可訪問的URL形式提供？

Q：多久能擷取識別結果？

故障排查

Q：一直輪詢不到結果？

Q：無法識別語音（無識別結果）是什麼原因？

`TranscriptionResponse`

`PENDING`狀態

`RUNNING`狀態

`SUCCEEDED`狀態

`FAILED`狀態

`TranscriptionOutput`

`SUCCEEDED`狀態

`FAILED`狀態

核心類（`Transcription`）