Alibaba Cloud Model Studio：Paraformer非即時語音辨識HTTP API

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

使用者指南：非即時語音辨識

目前提供了提交任務介面和查詢任務介面，通常情況下，您可以先調用提交任務介面上傳識別任務，然後迴圈調用查詢任務介面，直至任務完成。

前提條件

已開通服務並擷取API Key。請配置API Key到環境變數，而非寫入程式碼在代碼中，防範因代碼泄露導致的安全風險。

提交任務介面

基本資料

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

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

{
  "filter_with_signed": {
    "word_list": ["測試"]
  },
  "filter_with_empty": {
    "word_list": ["開始", "發生"]
  },
  "system_reserved_filter": true
}

響應參數

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

查詢任務介面

基本資料

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

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"

響應參數

{
  "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": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

識別結果說明

識別結果儲存為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":", "
                        }
                        // 這裡省略其它內容
                    ]
                }
            ]
        }
    ]
}

需要關注的參數如下：

完整樣本

您可以使用程式設計語言內建的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）：

使用SDK時，若錄音檔案儲存體在阿里雲OSS，不支援使用以 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的設定是否正確。
• 以上都沒問題，可通過定製熱詞，提升對特定詞語的識別效果。

更多問題

請參見GitHub QA。