調用Fun-ASR RESTful API識別錄音檔案-大模型服務平台百鍊-阿里雲_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

本文介紹Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR非即時語音辨識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

{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]
    }
}'

即時熱詞

使用即時熱詞時格式如下：

{
    "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（必選）

重要該參數為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
  }
}

異常樣本

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