Skip to main content
非即時語音辨識(Paraformer)

Paraformer非即時語音辨識HTTP API

本文介紹Paraformer非即時語音辨識HTTP API的參數和介面細節。

本文檔僅適用於華北2(北京)地區。如需使用模型,需使用華北2(北京)地區的API Key
阿里雲百鍊為華北2(北京)地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。
使用者指南:非即時語音辨識 目前提供了提交任務介面查詢任務介面,通常情況下,您可以先調用提交任務介面上傳識別任務,然後迴圈調用查詢任務介面,直至任務完成。

前提條件

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

提交任務介面

基本資料

介面描述提交語音辨識任務。
URL
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
要求方法POST
要求標頭
Authorization: Bearer {api-key} // 需替換為您自己的API Key
Content-Type: application/json
X-DashScope-Async: enable // 請勿遺漏該要求標頭,否則無法提交任務
訊息體包含所有請求參數的訊息體如下,對於可選欄位,在實際業務中可根據需求省略:
{
    "model":"paraformer-v2", //模型名,必選
    "input":{
        "file_urls":[
            "{YOUR_AUDIO_URL}"
        ] //待識別檔案,必選
    }
    "parameters":{
        "channel_id":[
            0
        ], //音軌索引,可選
        "disfluency_removal_enabled":false, //過濾語氣詞開關,可選
        "timestamp_alignment_enabled": false, //是否啟用時間戳記校準功能,可選
        "special_word_filter": "xxx", //敏感詞,可選
        "language_hints":[ // 當前該參數僅適用於paraformer-v2模型,其他模型不要使用該欄位
            "zh",
            "en"
        ],
        "diarization_enabled":false, //自動說話人分離,可選
        "speaker_count": 2 //說話人數量參考,可選
    }
}

請求參數

以下為調用提交任務介面的cURL樣本:
curl --location 'https://{WorkspaceId}.cn-beijing.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":"paraformer-v2","input":{"file_urls":["{YOUR_AUDIO_URL}"]},"parameters":{"channel_id":[0]}}'
參數類型預設值是否必須說明
modelstring
指定用於音視頻檔案轉寫的Paraformer模型名。參見支援的模型
file_urlsarray[string]
音視頻檔案轉寫的URL列表,支援HTTP / HTTPS協議,單次請求僅支援1個URL。
URL中如果包含空格、中文或其他特殊字元,必須先進行URL編碼(例如將空格替換為%20),否則可能導致檔案下載失敗,返回InvalidFile.DownloadFailed錯誤。
若錄音檔案儲存體在阿里雲OSS,使用RESTful API方式支援使用以 oss://為首碼的臨時 URL。
  • 臨時 URL 有效期間48小時,到期後無法使用,請勿用於生產環境。
  • 檔案上傳憑證介面限流為 100 QPS 且不支援擴容,請勿用於生產環境、高並發及壓測情境。
  • 生產環境建議使用阿里雲OSS 等穩定儲存,確保檔案長期可用並規避限流問題。
vocabulary_idstring
最新熱詞ID,支援最新v2系列模型並配置語種資訊,此次語音辨識中生效此熱詞ID對應的熱詞資訊。預設不啟用。使用方法請參考定製熱詞
channel_idarray[integer][0]指定在多音軌音頻檔案中需要識別的音軌索引,索引從 0 開始。例如,[0] 表示識別第一個音軌,[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數,則預設處理第一個音軌。
指定的每一個音軌都將獨立計費。例如,為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。
disfluency_removal_enabledbooleanfalse過濾語氣詞,預設關閉。
timestamp_alignment_enabledbooleanfalse是否啟用時間戳記校準功能,預設關閉。
special_word_filterstring
指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。若未傳入該參數,系統將啟用系統內建的敏感詞過濾邏輯,識別結果中與阿里雲百鍊敏感詞表匹配的詞語將被替換為等長的*若傳入該參數,則可實現以下敏感詞處理策略:
  • 替換為 *:將匹配的敏感詞替換為等長的 *
  • 直接過濾:將匹配的敏感詞從識別結果中完全移除。
該參數的值應為一個 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時,將同時啟用系統內建的敏感詞過濾邏輯,識別結果中與阿里雲百鍊敏感詞表匹配的詞語將被替換為等長的*
language_hintsarray[string]["zh", "en"]指定待識別語音的語言代碼。該參數僅適用於paraformer-v2模型。支援的語言代碼:
  • zh: 中文
  • en: 英文
  • ja: 日語
  • yue: 粵語
  • ko: 韓語
  • de:德語
  • fr:法語
  • ru:俄語
diarization_enabledbooleanfalse自動說話人分離,預設關閉。僅適用於單聲道音頻,多頻道音訊不支援說話人分離。啟用該功能後,識別結果中將顯示speaker_id欄位,用於區分不同說話人。
如果啟用說話人分離功能,建議音頻時間長度不超過2小時,否則可能導致識別失敗或逾時。
有關speaker_id的樣本,請參見識別結果說明
speaker_countinteger
說話人數量參考值。取值範圍為2至100的整數(包含2和100)。開啟說話人分離功能後(diarization_enabled設定為true)生效。預設自動判斷說話人數量,如果配置此項,只能輔助演算法盡量輸出指定人數,無法保證一定會輸出此人數。

響應參數

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

參數

類型

說明

task_status

string

任務狀態。

task_id

string

任務ID。該ID在查詢任務介面中作為請求參數傳入。

查詢任務介面

基本資料

介面描述查詢語音辨識任務執行情況和結果。
URL
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
要求方法POST
要求標頭
Authorization: Bearer {api-key} // 需替換為您自己的API Key
訊息體無。

請求參數

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}' --header "Authorization: Bearer $DASHSCOPE_API_KEY"

參數

類型

預設值

是否必須

說明

task_id

string

-

查詢任務需指定其ID,該ID為提交任務介面被調用後返回的task_id

響應參數

當任務包含多個子任務時,只要存在任一子任務成功,整個任務狀態將標記為SUCCEEDED,需通過subtask_status欄位判斷具體子任務結果。
  • 正常樣本
  • 異常樣本
{
  "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

string

被查詢任務的ID。

task_status

string

被查詢任務的狀態。

當任務包含多個子任務時,只要存在任一子任務成功,整個任務狀態將標記為SUCCEEDED,需通過subtask_status欄位判斷具體子任務結果。

subtask_status

string

子任務狀態。

file_url

string

檔案轉寫任務中所處理的檔案URL。

transcription_url

string

擷取識別結果對應的連結。該連結有效期間為24小時,逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。

識別結果儲存為JSON檔案,您可以通過上述連結下載該檔案或直接通過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_format

string

源檔案中音訊格式。

channels

array[integer]

源檔案中音訊音軌索引資訊,對單軌音頻返回[0],對雙軌音頻返回[0, 1],以此類推。

original_sampling_rate

integer

源檔案中音訊採樣率(Hz)。

original_duration

integer

源檔案中的原始音頻時間長度(ms)。

channel_id

integer

轉寫結果的音軌索引,以0為起始。

content_duration

integer

音軌中被判定為語音內容的時間長度(ms)。

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

transcript

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 time

api_key = "your-dashscope-api-key"  # 在此處替換為您的API Key
file_urls = [
    "{YOUR_AUDIO_URL}",
]
language_hints = ["zh", "en"]

# 提交檔案轉寫任務,包含待轉寫檔案url列表
def submit_task(apikey, file_urls) -> str:

    headers = {
        "Authorization": f"Bearer {apikey}",
        "Content-Type": "application/json",
        "X-DashScope-Async": "enable",
    }
    data = {
        "model": "paraformer-v2",
        "input": {"file_urls": file_urls},
        "parameters": {
            "channel_id": [0],
            "language_hints": language_hints
        },
    }
    # 錄音檔案轉寫服務url
    service_url = (
        "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/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)

錯誤碼

如遇報錯問題,請參見錯誤碼進行排查。 若問題仍未解決,請加入開發人員群反饋遇到的問題,並提供Request ID,以便進一步排查問題。 當任務包含多個子任務時,只要存在任一子任務成功,整個任務狀態將標記為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": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

更多樣本

更多樣本,請參見GitHub

常見問題

功能特性

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:識別結果和語音播放不同步怎麼辦?

請求參數timestamp_alignment_enabled設為true將啟用時間戳記校準功能,能夠讓識別結果和語音播放同步。

Q:提交任務後返回InvalidFile.DownloadFailed錯誤怎麼辦?

請檢查檔案URL中是否包含空格、中文等特殊字元。如果檔案名稱包含空格(例如"第八節 學生傷害事故處理辦法.mp4"),需要將空格替換為%20進行URL編碼後再傳入file_urls參數。

Q:錄音檔案URL設定成OSS臨時公網訪問不通該如何處理?

headers中將X-DashScope-OssResourceResolve設為enable 不推薦該方式。 Java SDK或者Python SDK不支援對headers進行配置。

Q:一直輪詢不到結果?

可能是限流原因,請耐心等待。若需擴容,請加入開發人員群進行申請。

Q:無法識別語音(無識別結果)是什麼原因?

  • 請檢查音頻是否符合要求(格式、採樣率)。
  • 若是使用了paraformer-v2模型,檢查language_hints的設定是否正確。
  • 以上都沒問題,可通過定製熱詞,提升對特定詞語的識別效果。

更多問題

請參見GitHub QA
文本產生
映像產生
視頻產生
音頻
Realtime API
  • 概述
向量與排序
模型生產