Skip to main content

Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR非即時語音辨識HTTP API參考

本文介紹Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR非即時語音辨識HTTP API的參數和介面細節。

使用者指南：非即時語音辨識。關於支援的音頻格式、檔案大小限制、時間長度限制等輸入要求，請參見音頻規格。

流程說明

與DashScope同步調用（一次請求、立即返回結果）不同，非同步呼叫專為處理長音頻檔案或耗時較長的任務設計，該模式採用“提交-輪詢”的兩步式流程，避免了因長時間等待而導致的請求逾時：
  1. 第一步：提交任務
    • 用戶端發起一個非同步處理請求。
    • 伺服器驗證請求後，不會立即執行任務，而是返回一個唯一的 task_id，表示任務已成功建立。
  2. 第二步：擷取結果
    • 用戶端使用擷取到的 task_id，通過輪詢方式反覆調用結果查詢介面。
    • 當任務處理完成後，結果查詢介面將返回最終的識別結果。

介面地址

  • 新加坡
  • 華北2（北京）
提交任務介面：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（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：
  • 華北2（北京）地區：從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區：從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。
使用新版網域名稱（https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com）提交任務時，請求參數中必須包含parameters對象。即使無需設定任何參數，也必須傳入Null 物件{}，否則任務可正常提交，但識別將失敗。

要求標頭

參數

類型

是否必選

說明

Authorization

string

是

鑒權令牌，格式為Bearer <your_api_key>，使用時，將"<your_api_key>"替換為實際的API Key。提交任務介面和查詢任務介面均需要傳入。

Content-Type

string

是

請求參數的媒體類型。僅提交任務介面需要傳入，固定為application/json。

X-DashScope-Async

string

是

非同步任務標識。僅提交任務介面需要傳入，固定為enable，請勿遺漏，否則無法提交任務。

提交任務介面

提交語音辨識任務。該介面非同步返回，業務側需結合查詢任務介面輪詢任務狀態。

請求參數

modelstring（必選）指定模型名。支援Qwen-Audio-3.0-ASR-Flash-Filetrans和Fun-ASR系列模型，詳情請參見支援的模型與地區。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)（可選）訊息列表。包含可選的對話上下文（用於提升識別效果）。
SDK暫不支援該功能。
上下文功能用於提升專有詞彙的識別準確率，使用方法詳見上下文增強。約束：上下文訊息（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（可選）請求參數對象。
使用新版網域名稱（https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com）時，parameters為必填項。即使無需設定任何參數，也必須傳入Null 物件{}。若省略該欄位，任務可正常提交，但查詢任務結果時將返回識別失敗。

屬性

vocabulary_id string（可選）先行編譯熱詞列表 ID。需預先調用建立熱詞列表介面產生，識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。使用方法請參見先行編譯熱詞。vocabulary object（可選）即時熱詞。以索引值對形式傳入，鍵為熱詞文本（string），值為熱詞權重（integer），無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50：取 [1, 5] 時值越大模型越傾向輸出該詞；取 50 時為超級熱詞，召回率大幅提升，但超級熱詞數量最多不超過 50 個。適用於臨時性、會話層級的熱詞最佳化。與先行編譯熱詞同時配置時，僅即時熱詞生效。使用方法請參見即時熱詞。
僅qwen-audio-3.0-asr-flash-filetrans支援即時熱詞。
channel_id array[integer]（可選）指定在多音軌音頻檔案中需要識別的音軌索引，索引從 0 開始。例如，[0] 表示識別第一個音軌，[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數，則預設處理第一個音軌。
指定的每一個音軌都將獨立計費。例如，為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。
預設值：[0]。special_word_filter string（可選）指定在語音辨識過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。diarization_enabled boolean（可選）是否啟用說話人分離，預設關閉。僅適用於單聲道音頻，多頻道音訊不支援說話人分離。啟用該功能後，識別結果中將顯示speaker_id欄位，用於區分不同說話人。
如果啟用說話人分離功能，建議音頻時間長度不超過2小時，否則可能導致識別失敗或逾時。
有關speaker_id的樣本，請參見識別結果說明。預設值：false。speaker_count integer（可選）
僅在開啟說話人分離功能（diarization_enabled設定為true）時生效。
說話人數量參考值。取值範圍為2至100的整數（包含2和100）。預設自動判斷說話人數量，如果配置此項，只能輔助演算法盡量輸出指定人數，無法保證一定會輸出此人數。無預設值。language_hints array[string]（可選）設定待識別語言代碼。如果無法提前確定語種，可不設定，模型會自動識別語種。對於 Qwen-Audio-3.0-ASR-Flash-Filetrans 系列模型，最多支援設定 4 個值，即便設定超出 4 個，也僅前 4 個生效；對於 Fun-ASR 系列模型，僅支援設定 1 個值，即便設定多個，也僅第一個生效。
  • qwen-audio-3.0-asr-flash-filetrans、fun-asr：
    • 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]
    }
}'

響應參數

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（必選）
該參數為URL路徑參數，無請求參數。
查詢任務需指定其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
  }
}

其他介面：批量查詢任務狀態/取消任務

詳情請參見管理非同步任務：支援批量查詢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）。

語音辨識模型服務僅對音軌中被判定為語音內容的時間長度進行語音轉寫，並據此進行計量計費，非語音內容不計量、不計費。通常情況下語音內容時間長度會短於原始音頻時間長度。由於對是否存在語音內容的判定是由AI模型給出的，可能與實際情況存在一定誤差。

transcript

string

段落層級的語音轉寫結果。

sentences

array

句子層級的語音轉寫結果。

words

array

詞層級的語音轉寫結果。

begin_time

integer

開始時間戳（ms）。

end_time

integer

結束時間戳記（ms）。

text

string

語音轉寫結果。

speaker_id

integer

當前說話人的索引，以0為起始，用於區分不同的說話人。

僅在啟用說話人分離功能時，該欄位才會顯示於識別結果中。

punctuation

string

預測出的詞之後的標點符號（如有）。