DocsICP FilingConsole
Documentation
Home Page OpenSearch AI Search Open Platform Developer Reference API reference Speech recognition

Speech recognition

Updated at:
Copy as MD
Product
My Favorites

AI Search Open Platform lets you call the speech recognition service through APIs to quickly convert speech in video or audio files into structured text. You can use the service in scenarios such as meeting minutes, video retrieval, and online customer service.

Services

Service name

Service ID (service_id)

Description

API call QPS limit (including the Alibaba Cloud account and its RAM users)

Speech recognition service

ops-audio-asr-001

Extracts audio information to generate subtitle files.

5

Note

To request a higher API QPS limit, submit a ticket to technical support.

  • Get authentication credentials

    The AI Search open platform requires an API key for authentication. For instructions, see Get an API key.

  • Get the service endpoint

    You can call the service via the public network or a VPC. For details, see Get the service endpoint.

Create an asynchronous speech recognition task

Request method: POST

URL

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

  • host: the endpoint used to call the service. You can call the API service over the Internet or a virtual private cloud (VPC). For more information, see Obtain a service endpoint.

    Log on to the AI Search Open Platform console. In the upper-left corner, select the target workspace, such as default (Default Workspace). In the left-side navigation pane, click API Keys. In the API Endpoints section, you can view the Public API Endpoint and the Private API Endpoint.

  • workspace_name: the name of the workspace, such as default.

  • service_id: the ID of the built-in service, such as ops-audio-asr-001.

Request parameters

Header parameters

API key authentication

Parameter

Type

Required

Description

Example

Content-Type

String

Yes

The request type: application/json.

application/json

Authorization

String

Yes

API-Key

Bearer OS-d1**2a

Body parameters

Parameter

Type

Required

Description

input

Object(input)

Yes

Specifies the multimedia file to be processed.

parameters

Object

No

Specifies the parameters of the service.

output

Object(output)

Yes

Controls the output.

input

Parameter

Type

Required

Description

content

String

No

The Base64-encoded data of the video or audio content.

Supported audio formats: mp3, wav, aac, flac, ogg, m4a, alac, and wma.

Supported video formats: mp4, avi, mkv, mov, flv, and webm.

Note

The input.content and input.oss parameters are mutually exclusive. You can specify only one of them.

To use Base64 data, pass the encoded Base64 data to the content parameter in the data:<TYPE>/<FORMAT>;base64,<BASE64_DATA> format, where:

  • <TYPE>/<FORMAT>

    • For audio, such as MP3, specify audio/mp3.

    • For video, such as MOV, specify video/mov.

  • <BASE64_DATA> : the Base64-encoded data of the audio or video.

Examples:

  • Audio: data:audio/mp3;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...

  • Video: data:video/mov;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...

oss

String

No

The OSS path of the input file, such as oss://<BUCKET_NAME>/xxx/xxx.mp3.

file_name

String

No

The name of the video or audio file. If this parameter is not specified, the name is parsed from the file name of the content.

output

Parameter

Type

Required

Description

type

String

No

text: returns the speech recognition result as text. This value is supported only for synchronous task calls.

oss: the audio file is stored in OSS. This is the default value.

oss

String

No

The OSS path of the output file. This parameter is required if type is set to oss.

Example: oss://<BUCKET_NAME>/result

Response parameters

Parameter

Type

Description

Example

result.task_id

String

The unique ID of the speech recognition task.

asr-xxxx-abc-123

Sample curl request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_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"
    }
  }' \

Sample response

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

Query the status of an asynchronous speech recognition task

Request method: GET

URL

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

  • host: the endpoint used to call the service. You can call the API service over the Internet or a virtual private cloud (VPC). For more information, see Obtain a service endpoint.

  • workspace_name: the name of the workspace, such as default.

  • service_id: the ID of the built-in service, such as ops-audio-asr-001.

  • task_id: the task ID returned in the response parameters when you create an asynchronous speech recognition task.

Request parameters

Parameter

Type

Required

Description

Example

Content-Type

String

Yes

The request type: application/json.

application/json

Authorization

String

Yes

API-Key

Bearer OS-d1**2a

Response parameters

Parameter

Type

Description

Example

request_id

String

The unique ID that the system assigns to the API call.

3C09570D-12DB-46B4-BF0F-A100D79B****

latency

Float/Int

The time taken to process the request. Unit: ms.

3.0

result.task_id

String

The ID of the asynchronous task.

a7e4c0f6-874c-47e3-b05b-02278a96e****

result.status

String

The status of the task:

  • PENDING: The task is pending.

  • SUCCESS: The task is successfully completed.

  • FAIL: The task failed and was terminated.

PENDING

result.error

String

The error message returned when status is FAIL. This parameter is empty in normal cases.

result.data

List(AsrResult)

The speech recognition result. This parameter is empty if the asynchronous task has not been successfully completed (SUCCESS).

usage.duration

Float.duration

The duration of the audio file.

AsrResult

Parameter

Type

Description

text

String

The text data obtained from speech recognition.

start

Float

The start timestamp of the current text in the video. Unit: seconds.

end

Float

The end timestamp of the current text in the video. Unit: seconds.

Sample curl request

curl -X GET \
-H"Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_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-******"

Sample response

{
  "request_id": "1a1a4ca4b7a91dd630a40c54af******",
  "latency": 9,
  "usage": {
    "duration": 9
  },
  "result": {
    "task_id": "asr-20250618112151-1108418170738252-******",
    "status": "SUCCESS",
    "data": [
      {
        "text": "The singer tells the story gently in a head voice as warm as spring sunshine,",
        "start": 0.0,
        "end": 3.9
      },
      {
        "text": "radiating a thriving vitality that warms every listening ear.",
        "start": 4.24,
        "end": 9.06
      }
    ]
  }
}

Create a synchronous speech recognition task

Request method: POST

URL

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

  • host: the endpoint used to call the service. You can call the API service over the Internet or a virtual private cloud (VPC). For more information, see Obtain a service endpoint.

  • workspace_name: the name of the workspace, such as default.

  • service_id: the ID of the built-in service, such as ops-audio-asr-001.

Request parameters

Header parameters

API key authentication

Parameter

Type

Required

Description

Example

Content-Type

String

Yes

The request type: application/json.

application/json

Authorization

String

Yes

API-Key

Bearer OS-d1**2a

Body parameters

Parameter

Type

Required

Description

input

Object(input)

Yes

Specifies the multimedia file to be processed.

parameters

Object

No

Specifies the parameters of the service.

output

Object(output)

Yes

Controls the output.

input

Parameter

Type

Required

Description

content

String

No

The Base64-encoded data of the video or audio content.

Supported audio formats: mp3, wav, aac, flac, ogg, m4a, alac, and wma.

Supported video formats: mp4, avi, mkv, mov, flv, and webm.

Note

The input.content and input.oss parameters are mutually exclusive. You can specify only one of them.

To use Base64 data, pass the encoded Base64 data to the content parameter in the data:<TYPE>/<FORMAT>;base64,<BASE64_DATA> format, where:

  • <TYPE>/<FORMAT>

    • For audio, such as MP3, specify audio/mp3.

    • For video, such as MOV, specify video/mov.

  • <BASE64_DATA> : the Base64-encoded data of the audio or video.

Examples:

  • Audio: data:audio/mp3;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...

  • Video: data:video/mov;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...

oss

String

No

The OSS path of the input file, such as oss://<BUCKET_NAME>/xxx/xxx.mp3.

file_name

String

No

The name of the video or audio file. If this parameter is not specified, the name is parsed from the file name of the content.

Output

Parameter

Type

Required

Description

type

String

No

text: returns the speech recognition result as text. This value is supported only for synchronous calls.

oss: the video or audio file is stored in OSS. This is the default value.

oss

String

No

The OSS path of the output file. This parameter is required if type is set to oss.

Example: oss://<BUCKET_NAME>/result

Response parameters

Parameter

Type

Description

Example

result.task_id

String

The unique ID of the speech recognition task.

asr-xxxx-abc-123

Sample curl request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_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"
    }
  }' \

Sample response

{
  "request_id": "df96b5c444281e0e79561fe9f8******",
  "latency": 570,
  "usage": {
    "duration": 9
  },
  "result": {
    "task_id": "asr-20250618132401-1108418170738252-******",
    "status": "SUCCESS",
    "data": [
      {
        "text": "The singer tells the story gently in a head voice as warm as spring sunshine,",
        "start": 0.0,
        "end": 3.9
      },
      {
        "text": "radiating a thriving vitality that warms every listening ear.",
        "start": 4.24,
        "end": 9.06
      }
    ]
  }
}

Status codes

If a request fails, the code and message parameters in the output indicate the cause of the error.

{
    "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 status code

Error code

Description

200

-

The request is successful, including cases where the task fails. Check result.status to determine the actual task status.

404

BadRequest.TaskNotExist

The task does not exist.

400

InvalidParameter

The request is invalid.

500

InternalServerError

An internal error occurred.

For more information about status codes, see Status codes.

Previous：Video segmentationNext：Document splitting