DocsICP FilingConsole
官方文档
首页

Speech recognition

更新时间：
复制 MD 格式
产品详情
我的收藏

AI Search Open Platform offers a speech recognition API that quickly converts speech from audio and video into structured text for meeting transcription, video search indexing, and online customer service.

Service list

Service name

Service ID

Description

API QPS limit

speech recognition service

ops-audio-asr-001

Generates subtitles from audio content.

5

Note

To request a higher QPS limit, submit a ticket.

  • Get authentication credentials

    All calls to the AI search open platform service require authentication with an API key. To obtain one, see Get an API key.

  • Get a service endpoint

    You can call the service over the public network or from a VPC. To get an endpoint, see Get a service endpoint.

Asynchronous speech recognition task

Request method: POST

URL

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

  • host: The service endpoint. You can call the API service over the public network or from a VPC. For more information, see Get a service endpoint.

    Log in to the AI Search Open Platform console. In the upper-left corner, select the target workspace, for example, default (default space). In the left-side navigation pane, click API Keys. In the access domain section, you can find the public API domain and private API domain.

  • workspace_name: The workspace name, e.g., default.

  • service_id: The built-in service ID, e.g., ops-audio-asr-001.

Request parameters

Header parameters

API key authentication

Parameter

Type

Required

Description

Example

Content-Type

String

Yes

The media type of the request body.

application/json

Authorization

String

Yes

API key

Bearer OS-d1**2a

Body parameters

Parameter

Type

Required

Description

input

Object(input)

Yes

The media file to process.

parameters

Object

No

Parameters for the service.

output

Object(output)

Yes

The output configuration.

input

Parameter

Type

Required

Description

content

String

No

The base64-encoded audio or video 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. Specify only one.

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

  • <TYPE>/<FORMAT>

    • For audio, such as mp3, use audio/mp3.

    • For video, such as mov, use video/mov.

  • <BASE64_DATA>: The BASE64-encoded audio or video data.

Examples:

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

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

oss

String

No

The OSS path of the input file. For example, oss://<bucket_name>/path/to/file.mp3.

file_name

String

No

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

Output

Parameter

Type

Required

Description

type

String

No

text: Returns the speech recognition result as plain text. This option is supported only for synchronous tasks.

oss: Stores the output file in an OSS bucket. This is the default.

oss

String

No

The OSS path for the output file. Required if type is set to oss.

Example: oss://<BUCKET_NAME>/result

Response parameters

Parameter

Type

Description

Example value

result.task_id

String

A unique identifier for the speech recognition task.

asr-xxxx-abc-123

Curl example

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"
    }
  }' \

Response example

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

Asynchronous speech recognition task status

Request method: GET

URL

  • host: The service endpoint. You can call the API service over the public network or from a VPC. For more information, see Get a service endpoint.

  • workspace_name: The name of the workspace, for example, default.

  • service_id: The built-in service ID, for example, ops-audio-asr-001.

  • task_id: The unique ID for the asynchronous speech recognition task, returned in the response when the task is created.

Request parameters

Parameter

Type

Required

Description

Example

Content-Type

String

Yes

The media type of the request.

application/json

Authorization

String

Yes

The API key for authentication.

Bearer OS-d1**2a

Response parameters

Parameter

Type

Description

Example

request_id

String

The request ID.

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

latency

Float/Int

The request latency in milliseconds.

3.0

result.task_id

String

The asynchronous task ID.

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

result.status

String

The task status. Valid values are:

  • PENDING: The task is awaiting processing.

  • SUCCESS: The task completed successfully.

  • FAIL: The task failed due to an error.

PENDING

result.error

String

The error message. This field has a value only when result.status is FAIL.

result.data

List(AsrResult)

The speech recognition results. This field is populated only when the asynchronous task status is SUCCESS.

usage.duration

Float

The duration of the audio file, in seconds.

AsrResult

Parameter

Type

Description

text

String

The transcribed text from speech recognition.

start

Float

The start timestamp of the text in the video, in seconds.

end

Float

The end timestamp of the text in the video, in seconds.

Example: 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-******"

Response example

{
  "request_id": "1a1a4ca4b7a91dd630a40c54af******",
  "latency": 9,
  "usage": {
    "duration": 9
  },
  "result": {
    "task_id": "asr-20250618112151-1108418170738252-******",
    "status": "SUCCESS",
    "data": [
      {
        "text": "Rong Jielvdou began to speak, his voice as warm as the spring sun,",
        "start": 0.0,
        "end": 3.9
      },
      {
        "text": "full of life and warming the hearts of everyone who listened.",
        "start": 4.24,
        "end": 9.06
      }
    ]
  }
}

Creating a synchronous speech recognition task

Request method: POST

URL

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

  • host: The service endpoint. You can call the API service via the public network or a VPC. For more information, see Get a service endpoint.

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

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

Request parameters

Header parameter

API key authentication

Parameter

Type

Required

Description

Example

Content-Type

String

Yes

Specifies the media type of the request body.

application/json

Authorization

String

Yes

The API key for authentication, prefixed with "Bearer ".

Bearer OS-d1**2a

Body parameters

Parameter

Type

Required

Description

input

Object(input)

Yes

The media file to process.

parameters

Object

No

Parameters for the service.

output

Object(output)

Yes

The output configuration.

input

Parameter

Type

Required

Description

content

String

No

The base64-encoded audio or video 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. Specify only one.

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

  • <TYPE>/<FORMAT>

    • For audio, such as mp3, use audio/mp3.

    • For video, such as mov, use video/mov.

  • <BASE64_DATA>: The BASE64-encoded audio or video data.

Examples:

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

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

oss

String

No

The OSS path of the input file. For example, oss://<bucket_name>/path/to/file.mp3.

file_name

String

No

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

Output

Parameter

Type

Required

Description

type

String

No

text: Returns the speech recognition result as plain text. This option is only available for synchronous calls.

oss: Stores the video or audio file in OSS (default).

oss

String

No

The OSS path for the output file. Required when type is oss.

example: oss://<BUCKET_NAME>/result

Response parameters

Parameter

Type

Description

Example value

result.task_id

String

A unique identifier for the speech recognition task.

asr-xxxx-abc-123

Curl request

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.mp3"
    },
    "output":{
      "type":"oss",
      "oss":"oss://<BUCKET_NAME>/result"
    }
  }' \

Response example

{
  "request_id": "df96b5c444281e0e79561fe9f8******",
  "latency": 570,
  "usage": {
    "duration": 9
  },
  "result": {
    "task_id": "asr-20250618132401-1108418170738252-******",
    "status": "SUCCESS",
    "data": [
      {
        "text": "Rong Jielvdou began to speak, his voice as warm as the spring sun,",
        "start": 0.0,
        "end": 3.9
      },
      {
        "text": "full of life and warming the hearts of everyone who listened.",
        "start": 4.24,
        "end": 9.06
      }
    ]
  }
}

Status codes

If an access request fails, the output includes a code and message that explain 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 even if the task fails. Check result.status for the actual task status.

404

BadRequest.TaskNotExist

The specified task does not exist.

400

InvalidParameter

The request is invalid.

500

InternalServerError

An internal error occurred.

For more on status codes, see Status Code Description.

Previous：Video segmentationNext：Document chunking