調用語音辨識服務API-智能OpenSearch OpenSearch-阿里雲 - OpenSearch

AI搜尋開放平台支援通過API的方式調用語音辨識服務，可將視頻或音頻中的語音內容快速轉化為結構化文本，可用於會議記錄、視頻檢索、線上客服等情境。

服務列表

服務名稱	服務ID（service_id）	服務描述	API調用QPS限制（含主帳號與RAM子帳號）
語音辨識服務	ops-audio-asr-001	提取音頻資訊產生字幕檔案。	5 說明如需擴充QPS，請通過工單聯絡支援人員協助。

擷取身份鑒權資訊
通過API調用AI搜尋開放平台服務時，需要對調用者身份進行鑒權，如何擷取鑒權資訊請參見擷取API-KEY。
擷取服務調用地址
支援通過公網和VPC兩種方式調用服務，詳情請參見擷取服務接入地址。

建立語音辨識非同步任務

請求方式：POST

URL

POST {host}/v3/openapi/workspaces/{workspace_name}/audio-asr/{service_id}/async

host：調用服務的地址，支援通過公網和VPC兩種方式調用API服務，可參見擷取服務接入地址。

登入AI搜尋開放平台控制台，在左上方選擇目標工作空間（如default(預設空間)），在左側導覽列單擊API Keys，在訪問網域名稱地區可分別查看公網API網域名稱和私網API網域名稱。

workspace_name：工作空間名稱，例如default。
service_id：系統內建服務ID，例如ops-audio-asr-001。

請求參數

Header參數

API-KEY認證

參數	類型	必填	描述	樣本值
Content-Type	String	是	請求類型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body參數

參數	類型	必填	描述
input	Object(input)	是	指定待處理的多媒體檔案。
parameters	Object	否	指定服務的參數。
output	Object(output)	是	控制輸出。

input

參數	類型	必填	描述
content	String	否	視頻/音頻內容的base64編碼資料。音頻格式支援mp3、wav、aac、flac、ogg、m4a、alac、wma。視頻格式資料支援mp4、avi、mkv、mov、flv、webm。說明 input.content 和 input.oss 參數互斥，只能二選一。使用BASE64資料：將編碼後的BASE64資料傳遞給`content` 參數，格式為`data:<TYPE>/<FORMAT>;base64,<BASE64_DATA>` ，其中： `<TYPE>/<FORMAT>` 若為音頻（如MP3），則填寫audio/mp3。若為視頻（如MOV），則填寫video/mov。 `<BASE64_DATA>` ：音頻或視頻的BASE64編碼資料。樣本：音頻：data:audio/mp3;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj... 視頻：data:video/mov;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	否	輸入檔案的OSS路徑，例如 oss://<BUCKET_NAME>/xxx/xxx.mp3。
file_name	String	否	視頻/音頻檔案的名稱，如果沒有設定，則從內容的檔案名稱中解析。

output

參數

類型

必填

描述

type

String

否

text：將語音辨識結果以文本形式返回，僅同步任務調用下支援。

oss: 音頻檔案放在OSS中（預設）。

oss

String

否

輸出檔案的OSS路徑，在type為oss的情況下必須填寫。

樣本：oss://<BUCKET_NAME>/result

返回參數

參數	類型	描述	樣本值
result.task_id	String	語音辨識任務的唯一標識ID。	asr-xxxx-abc-123

Curl請求樣本

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <您的API-KEY>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/audio-asr/ops-audio-asr-001/async"
  --data '{
  "input":{
      "oss":"oss://<BUCKET_NAME>/xxx/xxx.mp3",
      "file_name":"xxx"
    },
    "output" :{
      "type":"oss",
      "oss":"oss://<BUCKET_NAME>/result"
    }
  }' \

響應樣本

{
  "request_id":"3eb8de02091b59431601f3bff******",
   "latency":37,
   "usage":{},
   "result":{
         "task_id":"asr-20250610164552-1108418170738252-******",
         "status":"PENDING"
             }
}

擷取非同步語音辨識任務狀態

請求方式：GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/audio-asr/{service_id}/async/task-status?task_id={task_id}

host：調用服務的地址，支援通過公網和VPC兩種方式調用API服務，可參見擷取服務接入地址。
workspace_name：工作空間名稱，例如default。
service_id：系統內建服務ID，例如ops-audio-asr-001。
task_id：建立非同步語音辨識任務返回參數中的任務標識。

請求參數

參數	類型	必填	描述	樣本
Content-Type	String	是	請求類型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

返回參數

參數	類型	描述	樣本
request_id	String	系統對一次API調用賦予的唯一標識。	3C09570D-12DB-46B4-BF0F-A100D79B****
latency	Float/Int	請求耗時，單位ms。	3.0
result.task_id	String	非同步任務ID。	a7e4c0f6-874c-47e3-b05b-02278a96e****
result.status	String	任務狀態： PENDING：待處理。 SUCCESS：任務成功完成。 FAIL：任務失敗終止。	PENDING
result.error	String	status=FAIL時的錯誤資訊內容，正常情況為空白。
result.data	List(AsrResult)	語音辨識的結果。當非同步任務狀態未成功完成（SUCCESS）時，該欄位為空白。
usage.duration	Float.duration	語音檔案的時間長度。

AsrResult

參數	類型	描述
text	String	語音辨識得到的文本資料。
start	Float	當前文本在視頻中起始時間戳記，單位s。
end	Float	當前文本在視頻中結束時間戳記，單位s。

Curl請求樣本

curl -X GET \
-H"Content-Type: application/json" \
-H "Authorization: Bearer <您的API-KEY>" \
"http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/audio-asr/ops-audio-asr-001/async/task-status?task_id=asr-20250618112151-1108418170738252-******"

響應樣本

{
  "request_id": "1a1a4ca4b7a91dd630a40c54af******",
  "latency": 9,
  "usage": {
    "duration": 9
  },
  "result": {
    "task_id": "asr-20250618112151-1108418170738252-******",
    "status": "SUCCESS",
    "data": [
      {
        "text": "容傑律鬥以和煦如春陽的頭聲娓娓道來,",
        "start": 0.0,
        "end": 3.9
      },
      {
        "text": "透出了欣欣向榮的生命力,溫暖每一個傾聽的耳朵。",
        "start": 4.24,
        "end": 9.06
      }
    ]
  }
}

建立語音辨識同步任務

請求方式：POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/audio-asr/{service_id}/sync

host：調用服務的地址，支援通過公網和VPC兩種方式調用API服務，可參見擷取服務接入地址。
workspace_name：工作空間名稱，例如default。
service_id：系統內建服務ID，例如ops-audio-asr-001。

請求參數

Header參數

API-KEY認證

參數	類型	必填	描述	樣本值
Content-Type	String	是	請求類型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body參數

參數	類型	必填	描述
input	Object(input)	是	指定待處理的多媒體檔案。
parameters	Object	否	指定服務的參數。
output	Object(output)	是	控制輸出。

input

參數	類型	必填	描述
content	String	否	視頻/音頻內容的base64編碼資料。音頻格式支援mp3、wav、aac、flac、ogg、m4a、alac、wma。視頻格式資料支援mp4、avi、mkv、mov、flv、webm。說明 input.content 和 input.oss 參數互斥，只能二選一。使用BASE64資料：將編碼後的BASE64資料傳遞給`content` 參數，格式為`data:<TYPE>/<FORMAT>;base64,<BASE64_DATA>` ，其中： `<TYPE>/<FORMAT>` 若為音頻（如MP3），則填寫audio/mp3。若為視頻（如MOV），則填寫video/mov。 `<BASE64_DATA>` ：音頻或視頻的BASE64編碼資料。樣本：音頻：data:audio/mp3;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj... 視頻：data:video/mov;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	否	輸入檔案的OSS路徑，例如 oss://<BUCKET_NAME>/xxx/xxx.mp3。
file_name	String	否	視頻/音頻檔案的名稱，如果沒有設定，則從內容的檔案名稱中解析。

Output

參數

類型

必填

描述

type

String

否

text：將語音辨識結果以文本形式返回，僅同步調用下支援。

oss：視頻/音頻檔案放在OSS中（預設）。

oss

String

否

輸出檔案的OSS路徑，在type為oss的情況下必須填寫。

樣本：oss://<BUCKET_NAME>/result

返回參數

參數	類型	描述	樣本值
result.task_id	String	語音辨識任務的唯一標識ID。	asr-xxxx-abc-123

Curl請求樣本

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <您的API-KEY>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/audio-asr/ops-audio-asr-001/sync"
  --data '{
  "input":{
      "oss":"oss://<BUCKET_NAME>/xxx/xxx.mp3",
      "file_name":"xxx"
    },
    "output" :{
      "type":"oss",
      "oss":"oss://<BUCKET_NAME>/result"
    }
  }' \

響應樣本

{
  "request_id": "df96b5c444281e0e79561fe9f8******",
  "latency": 570,
  "usage": {
    "duration": 9
  },
  "result": {
    "task_id": "asr-20250618132401-1108418170738252-******",
    "status": "SUCCESS",
    "data": [
      {
        "text": "容傑律鬥以和煦如春陽的頭聲娓娓道來,",
        "start": 0.0,
        "end": 3.9
      },
      {
        "text": "透出了欣欣向榮的生命力,溫暖每一個傾聽的耳朵。",
        "start": 4.24,
        "end": 9.06
      }
    ]
  }
}

狀態代碼說明

在訪問請求出錯的情況下，輸出的結果中會通過code和message指明出錯原因。

{
    "request_id": "6F33AFB6-A35C-4DA7-AFD2-9EA16CCF****",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\"
}

HTTP 狀態代碼	錯誤碼	描述
200	-	請求成功，包括任務失敗情境，實際任務狀態需從result.status中判斷。
404	BadRequest.TaskNotExist	任務不存在。
400	InvalidParameter	不合法請求。
500	InternalServerError	內部錯誤。

更多狀態代碼說明，請參見狀態代碼說明。