Skip to main content

Qwen-Audio-ASR-Filetrans非即時語音辨識Python SDK

本文介紹Qwen-Audio-ASR-Filetrans非即時語音辨識Python SDK的參數和介面細節。

關於支援的音頻格式、檔案大小限制、時間長度限制等輸入要求,請參見音頻規格。

前提條件

快速開始

以下範例使用 DashScope Python SDK 2.0。核心資源(client.audio.asr)提供任務提交、等待和查詢介面,可透過以下兩種方式呼叫:
  • 非同步提交任務+同步等待任務結束:提交任務後,阻塞當前線程直到任務結束並擷取識別結果。
  • 非同步提交任務+非同步查詢任務執行結果:提交任務後,在需要的時候通過調用查詢任務介面擷取任務的執行結果。
  • 非同步提交任務+同步等待任務結束
  • 非同步提交任務+非同步查詢任務執行結果
提交任務並同步等待
  1. 呼叫 client.audio.asr.jobs.create 提交任務並設定請求參數。
    • 檔案轉寫服務對通過API提交的任務採取儘力服務原則進行處理。任務提交後將進入排隊(PENDING)狀態,排隊時間取決於隊列長度和檔案時間長度,無法明確給出,通常在數分鐘內。任務開始處理後,語音辨識將以數百倍加速完成。
    • 每一個任務完成後,識別結果和URL下載連結有效期間為24小時,逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。
  2. 呼叫 client.audio.asr.jobs.wait(job=job) 同步等待任務結束。 任務處於 PENDING 或 RUNNING 狀態時,jobs.wait 持續等待;任務成功後傳回 Job。 介面傳回 Job,可透過 job.results 取得結果清單,其中的 transcription_url 為轉寫結果下載位址。
import json
import os

import dashscope

# 將 {WorkspaceId} 替換為對應地區的真實業務空間 ID。
client = dashscope.Client(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

job = client.audio.asr.jobs.create(
    model="qwen-audio-3.0-asr-flash-filetrans",
    file_urls=["{YOUR_AUDIO_URL}"],
)

job = client.audio.asr.jobs.wait(job=job)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))

介面地址

SDK 預設使用北京地區。建立 dashscope.Client 時,透過 region 指定地區,透過 workspace 指定業務空間。地區設定僅作用於該 Client。
  • 新加坡
  • 華北2(北京)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1調用時請將{WorkspaceId}替換為真實的業務空間ID。
不同地區的 API Key 不同,請使用對應地區的 API Key。

請求參數

透過 client.audio.asr.transcribe 或 client.audio.asr.jobs.create 設定請求參數。
參數類型是否必須說明
modelstr是模型名稱。
file_urlslist[str]是音視頻檔案轉寫的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不支援對要求標頭進行配置。
parameters.keep_dialectbool否僅 qwen-audio-3.1-asr-flash-filetrans 支援。預設值為 false:將方言轉寫為普通話;設為 true 時保留方言表達。
parameters.vocabulary_idstr否先行編譯熱詞列表 ID。需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。使用方法請參見先行編譯熱詞。
parameters.vocabularydict否即時熱詞。以索引值對形式傳入,鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50:取 [1, 5] 時值越大模型越傾向輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞數量最多不超過 50 個。適用於臨時性、會話層級的熱詞最佳化。與預編譯熱詞同時設定時,系統會合併兩類熱詞;合併後超過 2000 個時,隨機選擇 2000 個使用。使用方法請參見即時熱詞。樣本:以下範例重用快速入門中已設定地區和業務空間的 client。
vocab = {"張三": 5, "李四": 5}
result = client.audio.asr.jobs.create(
    model="qwen-audio-3.0-asr-flash-filetrans",
    file_urls=["{YOUR_AUDIO_URL}"],
    parameters={"vocabulary": vocab},
)
parameters.channel_idlist[int]否指定在多音軌音頻檔案中需要識別的音軌索引,索引從 0 開始。例如,[0] 表示識別第一個音軌,[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數,則預設處理第一個音軌。
指定的每一個音軌都將獨立計費。例如,為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。
預設值:[0]。
parameters.special_word_filterstr否指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。
parameters.diarization_enabledbool否是否啟用說話人分離,預設關閉。僅適用於單聲道音頻,多頻道音訊不支援說話人分離。啟用該功能後,識別結果中將顯示speaker_id欄位,用於區分不同說話人。
如果啟用說話人分離功能,建議音頻時間長度不超過2小時,否則可能導致識別失敗或逾時。
預設值:False。有關speaker_id的樣本,請參見識別結果說明。
parameters.speaker_countint否
僅在開啟說話人分離功能(diarization_enabled設定為True)時生效。
說話人數量參考值。取值範圍為2至100的整數(包含2和100)。預設自動判斷說話人數量,如果配置此項,只能輔助演算法盡量輸出指定人數,無法保證一定會輸出此人數。無預設值。
parameters.language_hintslist[str]否設定待識別語言代碼。如果無法提前確定語種,可不設定,模型會自動識別語種。最多支援設定 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:斯洛伐克語

響應結果

Job

Job 封裝任務資訊、原始輸出和用量資訊。
{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "status": "PENDING",
    "submitted_at": "2026-10-29 10:00:00.000",
    "scheduled_at": null,
    "finished_at": null,
    "output": {
        "task_id": "00000000-0000-0000-0000-000000000001",
        "task_status": "PENDING",
        "submit_time": "2026-10-29 10:00:00.000"
    },
    "usage": null
}
欄位說明
task_id任務 ID。
status任務狀態:PENDING、RUNNING、SUCCEEDED 或 FAILED。
submitted_at提交時間,對應 job.output["submit_time"]。
scheduled_at開始處理時間,對應 job.output["scheduled_time"]。
finished_at結束時間,對應 job.output["end_time"]。
output原始任務輸出字典。
results子任務結果清單,可透過 job.results 讀取;下載 transcription_url 指向的 JSON 檔案可取得辨識文字。
usage任務用量資訊。 qwen-audio-3.1-asr-flash-filetrans 使用 input_tokens、output_tokens 和 total_tokens 統計 Token 用量;qwen-audio-3.0-asr-flash-filetrans 按 duration 計量。

Job.output

job.output 是服務端傳回的原始任務輸出字典。
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED (raise_on_error=False)
{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "task_status": "PENDING",
    "submit_time": "2026-10-29 10:00:00.000"
}
參數說明
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":"{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_formatstring源檔案中音訊格式。
channelsarray[integer]源檔案中音訊音軌索引資訊,對單軌音頻返回[0],對雙軌音頻返回[0, 1],以此類推。
original_sampling_rateinteger源檔案中音訊採樣率(Hz)。
original_duration_in_millisecondsinteger源檔案中的原始音頻時間長度(ms)。
channel_idinteger轉寫結果的音軌索引,以0為起始。
content_durationinteger音軌中被判定為語音內容的時間長度(ms)。
以下計費說明適用於 qwen-audio-3.0-asr-flash-filetrans。qwen-audio-3.1-asr-flash-filetrans 按 Token 計費。
語音辨識模型服務僅對音軌中被判定為語音內容的時間長度進行語音轉寫,並據此進行計量計費,非語音內容不計量、不計費。通常情況下語音內容時間長度會短於原始音頻時間長度。由於對是否存在語音內容的判定是由AI模型給出的,可能與實際情況存在一定誤差。
transcriptstring段落層級的語音轉寫結果。
sentencesarray句子層級的語音轉寫結果。
wordsarray詞層級的語音轉寫結果。
begin_timeinteger開始時間戳(ms)。
end_timeinteger結束時間戳記(ms)。
textstring語音轉寫結果。
speaker_idinteger當前說話人的索引,以0為起始,用於區分不同的說話人。僅在啟用說話人分離功能時,該欄位才會顯示於識別結果中。
punctuationstring預測出的詞之後的標點符號(如有)。

關鍵介面

核心資源(client.audio.asr)

透過 dashscope.Client 建立用戶端後,使用 client.audio.asr 資源。以下方法均傳回 Job。
方法方法簽章說明
transcribe
def transcribe(
    file_urls: List[str],
    *,
    model: str = "qwen-audio-3.1-asr-flash-filetrans",
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: float = 86400.0,
    submit_timeout: Optional[float] = None,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
提交任務並同步等待完成。預設模型為 qwen-audio-3.1-asr-flash-filetrans;呼叫其他模型時明確設定 model。
jobs.create
def create(
    *,
    model: str,
    file_urls: List[str],
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
提交任務,傳回包含 task_id 和 status 的 Job,不等待辨識完成。
jobs.wait
def wait(
    job: Union[Job, str],
    *,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    timeout: float = 86400.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
傳入 Job 或任務 ID,同步等待任務完成。透過 poll_interval 和 max_interval 設定初始和最大輪詢間隔,透過 timeout 設定總等待時間,單位均為秒。
jobs.fetch
def fetch(
    task_id: str,
    *,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
透過任務 ID 查詢一次任務狀態和結果,不阻塞等待任務完成。

錯誤碼

任務失敗時,預設擲回 DashScopeError。如需取得失敗任務的 Job,在建立 Client 時設定 raise_on_error=False,並檢查 job.status。 如遇報錯問題,請參見錯誤碼進行排查。 當任務包含多個子任務時,只要存在任一子任務成功,整個任務狀態將標記為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": "{YOUR_AUDIO_URL}",
            "code": "FILE_DOWNLOAD_FAILED",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

常見問題

功能特性

Q:是否支援Base64編碼方式的音頻?

不支援Base64編碼方式的音頻。僅支援可通過公網訪問的 URL 所指向的音訊識別,不支援識別二進位流,也不支援直接識別本地檔案。

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

通常遵循以下幾個步驟(這裡為您提供一種思路,具體情況因不同儲存產品而異,推薦將音頻上傳至阿里雲OSS):
如以下這幾種:
  • Object Storage Service服務(推薦):
    • 使用雲端服務商的Object Storage Service服務(如阿里雲OSS),將音頻檔案上傳到儲存桶中,並設定為公開訪問。
    • 優點:高可用性、支援 CDN 加速、易於管理。
  • Web 服務器:
    • 將音頻檔案放置在支援 HTTP/HTTPS 訪問的 Web 服務器上(如 Nginx、Apache)。
    • 優點:適合小型專案或本地測試。
  • 內容分發網路(CDN):
    • 將音頻檔案託管在 CDN 上,通過 CDN 提供的 URL 訪問。
    • 優點:加速檔案傳輸,適合高並發情境。
根據選擇的儲存/託管方式,將音頻上傳,如:
  • Object Storage Service服務:
    • 登入雲端服務商的控制台,建立儲存桶。
    • 上傳音頻檔案,並設定檔案許可權為“公用讀取”或產生臨時訪問連結。
  • Web 服務器:
    • 將音頻檔案放置在伺服器指定目錄下(如 /var/www/html/audio/)。
    • 確保檔案可以通過 HTTP/HTTPS 訪問。
例如:
  • 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)。
公網環境下,確保產生的 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