本文介紹Paraformer非即時語音辨識HTTP API的參數和介面細節。
前提條件
已開通服務並擷取API Key。請配置API Key到環境變數,而非寫入程式碼在代碼中,防範因代碼泄露導致的安全風險。
提交任務介面
基本資料
| 介面描述 | 提交語音辨識任務。 |
| URL | |
| 要求方法 | POST |
| 要求標頭 | |
| 訊息體 | 包含所有請求參數的訊息體如下,對於可選欄位,在實際業務中可根據需求省略: |
請求參數
點擊查看請求樣本
點擊查看請求樣本
| 參數 | 類型 | 預設值 | 是否必須 | 說明 |
|---|---|---|---|---|
| model | string | 是 | 指定用於音視頻檔案轉寫的Paraformer模型名。參見支援的模型。 | |
| file_urls | array[string] | 是 | 音視頻檔案轉寫的URL列表,支援HTTP / HTTPS協議,單次請求僅支援1個URL。若錄音檔案儲存體在阿里雲OSS,使用RESTful API方式支援使用以 oss://為首碼的臨時 URL。 | |
| vocabulary_id | string | 否 | 最新熱詞ID,支援最新v2系列模型並配置語種資訊,此次語音辨識中生效此熱詞ID對應的熱詞資訊。預設不啟用。使用方法請參考定製熱詞。 | |
| channel_id | array[integer] | [0] | 否 | 指定在多音軌音頻檔案中需要識別的音軌索引,索引從 0 開始。例如,[0] 表示識別第一個音軌,[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數,則預設處理第一個音軌。 |
| disfluency_removal_enabled | boolean | false | 否 | 過濾語氣詞,預設關閉。 |
| timestamp_alignment_enabled | boolean | false | 否 | 是否啟用時間戳記校準功能,預設關閉。 |
| special_word_filter | string | 否 | 指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。若未傳入該參數,系統將啟用系統內建的敏感詞過濾邏輯,識別結果中與阿里雲百鍊敏感詞表匹配的詞語將被替換為等長的*。若傳入該參數,則可實現以下敏感詞處理策略:
| |
| language_hints | array[string] | ["zh", "en"] | 否 | 指定待識別語音的語言代碼。該參數僅適用於paraformer-v2模型。支援的語言代碼:
|
| diarization_enabled | boolean | false | 否 | 自動說話人分離,預設關閉。僅適用於單聲道音頻,多頻道音訊不支援說話人分離。啟用該功能後,識別結果中將顯示speaker_id欄位,用於區分不同說話人。如果啟用說話人分離功能,建議音頻時間長度不超過2小時,否則可能導致識別失敗或逾時。 speaker_id的樣本,請參見識別結果說明。 |
| speaker_count | integer | 否 | 說話人數量參考值。取值範圍為2至100的整數(包含2和100)。開啟說話人分離功能後(diarization_enabled設定為true)生效。預設自動判斷說話人數量,如果配置此項,只能輔助演算法盡量輸出指定人數,無法保證一定會輸出此人數。 |
響應參數
點擊查看響應樣本
點擊查看響應樣本
參數 | 類型 | 說明 |
|---|---|---|
task_status | string | 任務狀態。 |
task_id | string |
查詢任務介面
基本資料
| 介面描述 | 查詢語音辨識任務執行情況和結果。 |
| URL | |
| 要求方法 | POST |
| 要求標頭 | |
| 訊息體 | 無。 |
請求參數
點擊查看請求樣本
點擊查看請求樣本
參數 | 類型 | 預設值 | 是否必須 | 說明 |
|---|---|---|---|---|
task_id | string | - | 是 | 查詢任務需指定其ID,該ID為提交任務介面被調用後返回的 |
響應參數
點擊查看響應樣本
點擊查看響應樣本
SUCCEEDED,需通過subtask_status欄位判斷具體子任務結果。- 正常樣本
- 異常樣本
參數 | 類型 | 說明 |
|---|---|---|
task_id | string | 被查詢任務的ID。 |
task_status | string | 被查詢任務的狀態。 當任務包含多個子任務時,只要存在任一子任務成功,整個任務狀態將標記為 |
subtask_status | string | 子任務狀態。 |
file_url | string | 檔案轉寫任務中所處理的檔案URL。 |
transcription_url | string | 擷取識別結果對應的連結。該連結有效期間為24小時,逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。 識別結果儲存為JSON檔案,您可以通過上述連結下載該檔案或直接通過HTTP請求讀取該檔案中的內容。 JSON資料中各欄位含義請參見識別結果說明。 |
識別結果說明
識別結果儲存為JSON檔案。
點擊查看識別結果樣本
點擊查看識別結果樣本
參數 | 類型 | 說明 |
|---|---|---|
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為例,代碼如下:
錯誤碼
如遇報錯問題,請參見錯誤碼進行排查。
若問題仍未解決,請加入開發人員群反饋遇到的問題,並提供Request ID,以便進一步排查問題。
當任務包含多個子任務時,只要存在任一子任務成功,整個任務狀態將標記為SUCCEEDED,需通過subtask_status欄位判斷具體子任務結果。
錯誤返回樣本:
更多樣本
更多樣本,請參見GitHub。
常見問題
功能特性
Q:是否支援Base64編碼方式的音頻?
不支援Base64編碼方式的音頻。僅支援可通過公網訪問的 URL 所指向的音訊識別,不支援識別二進位流,也不支援直接識別本地檔案。
Q:如何將音頻檔案以公網可訪問的URL形式提供?
通常遵循以下幾個步驟(這裡為您提供一種思路,具體情況因不同儲存產品而異,推薦將音頻上傳至阿里雲OSS):
1、選擇儲存和託管方式
1、選擇儲存和託管方式
-
Object Storage Service服務(推薦):
- 使用雲端服務商的Object Storage Service服務(如阿里雲OSS),將音頻檔案上傳到儲存桶中,並設定為公開訪問。
- 優點:高可用性、支援 CDN 加速、易於管理。
-
Web 服務器:
- 將音頻檔案放置在支援 HTTP/HTTPS 訪問的 Web 服務器上(如 Nginx、Apache)。
- 優點:適合小型專案或本地測試。
-
內容分發網路(CDN):
- 將音頻檔案託管在 CDN 上,通過 CDN 提供的 URL 訪問。
- 優點:加速檔案傳輸,適合高並發情境。
2、上傳音頻檔案
2、上傳音頻檔案
-
Object Storage Service服務:
- 登入雲端服務商的控制台,建立儲存桶。
- 上傳音頻檔案,並設定檔案許可權為“公用讀取”或產生臨時訪問連結。
-
Web 服務器:
- 將音頻檔案放置在伺服器指定目錄下(如
/var/www/html/audio/)。 - 確保檔案可以通過 HTTP/HTTPS 訪問。
- 將音頻檔案放置在伺服器指定目錄下(如
3、產生公網可訪問的URL
3、產生公網可訪問的URL
-
Object Storage Service服務:
- 檔案上傳後,系統會自動產生一個公網存取 URL(通常格式為
https://<bucket-name>.<region>.aliyuncs.com/<file-name>)。 - 如果需要更友好的網域名稱,可以綁定自訂網域名並開啟 HTTPS。
- 檔案上傳後,系統會自動產生一個公網存取 URL(通常格式為
-
Web 服務器:
- 檔案的存取 URL 通常是伺服器位址加上檔案路徑(如
https://your-domain.com/audio/file.mp3)。
- 檔案的存取 URL 通常是伺服器位址加上檔案路徑(如
-
CDN:
- 配置 CDN 加速後,使用 CDN 提供的 URL(如
https://cdn.your-domain.com/audio/file.mp3)。
- 配置 CDN 加速後,使用 CDN 提供的 URL(如
4、驗證URL的可用性
4、驗證URL的可用性
- 在瀏覽器中開啟 URL,檢查是否能播放音頻檔案。
- 使用工具(如
curl或 Postman)驗證 URL 是否返回正確的 HTTP 響應(狀態代碼 200)。
oss://為首碼的臨時 URL。
使用RESTful API時,若錄音檔案儲存體在阿里雲OSS,支援使用以 oss://為首碼的臨時 URL:
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的設定是否正確。 - 以上都沒問題,可通過定製熱詞,提升對特定詞語的識別效果。