Custom hotwords HTTP API

Prerequisites

An API key configured as the DASHSCOPE_API_KEY environment variable

Endpoint

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token. Format: `Bearer $DASHSCOPE_API_KEY`.
Content-Type	string	Yes	Media type of the request body. Set to `application/json`.

Create a vocabulary

Request body

Parameter	Type	Required	Description
model	string	Yes	The custom vocabulary model. Set to `speech-biasing`.
input	object	Yes	The input parameters. See below.

Show input properties

Parameter	Type	Required	Description
action	string	Yes	The operation type. Set to `create_vocabulary`.
target_model	string	Yes	The speech recognition model that uses this vocabulary. Must match the model you specify when calling the speech recognition API.
prefix	string	Yes	A custom prefix for the vocabulary. Only lowercase letters and digits are allowed, max 10 characters.
vocabulary	array[object]	Yes	The vocabulary entries array. See Hotword entry structure.

Response body

Parameter	Type	Description
request_id	string	The unique identifier of this request.
output	object	The response data.
output.vocabulary_id	string	The ID of the created vocabulary.
usage	object	Usage information.
usage.count	integer	The number of vocabularies created. Always 1.

Show Example

Request

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "create_vocabulary",
    "target_model": "fun-asr",
    "prefix": "testpfx",
    "vocabulary": [
      {"text": "Seediq Bale", "weight": 4}
    ]
  }
}'

Response

{
  "output": {
    "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx"
  },
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

List vocabularies

Request body

Parameter	Type	Required	Description
model	string	Yes	Set to `speech-biasing`.
input	object	Yes	The input parameters. See below.

Show input properties

Parameter	Type	Required	Description
action	string	Yes	The operation type. Set to `list_vocabulary`.
prefix	string	No	Filter by vocabulary prefix.
page_index	integer	No	Page number, starting from 0. Default: 0.
page_size	integer	No	Number of entries per page. Default: 10.

Response body

Parameter	Type	Description
request_id	string	The unique identifier of this request.
output	object	The response data.
output.vocabulary_list	array[object]	The queried vocabularies.
usage	object	Usage information.
usage.count	integer	Always 1.

Each item in vocabulary_list contains:

Field	Type	Description
vocabulary_id	string	The vocabulary ID.
gmt_create	string	The creation time.
gmt_modified	string	The last modification time.
status	string	`OK`: Ready. `UNDEPLOYED`: Not available.

Show Example

Request

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "list_vocabulary",
    "prefix": "testpfx",
    "page_index": 0,
    "page_size": 10
  }
}'

Response

{
  "output": {
    "vocabulary_list": [
      {
        "gmt_create": "2026-03-02 18:07:38",
        "gmt_modified": "2026-03-02 18:07:38",
        "status": "OK",
        "vocabulary_id": "vocab-ciotest-8e74bef2accf4xxxxxxxx"
      },
      {
        "gmt_create": "2026-02-27 19:04:48",
        "gmt_modified": "2026-02-28 13:40:40",
        "status": "OK",
        "vocabulary_id": "vocab-sifasr-f483ad46e1844fxxxxxxxx"
      }
    ]
  },
  "usage": {
    "count": 1
  },
  "request_id": "81d51a05-8cdd-45c0-973f-xxxxxxxx"
}

Get a vocabulary

Request body

Parameter	Type	Required	Description
model	string	Yes	Set to `speech-biasing`.
input	object	Yes	The input parameters. See below.

Show input properties

Parameter	Type	Required	Description
action	string	Yes	The operation type. Set to `query_vocabulary`.
vocabulary_id	string	Yes	The ID of the vocabulary to get.

Response body

Parameter	Type	Description
request_id	string	The unique identifier of this request.
output	object	The response data.
usage	object	Usage information.
usage.count	integer	Always 1.

The output object contains:

Field	Type	Description
gmt_create	string	The creation time.
gmt_modified	string	The last modification time.
status	string	`OK`: Ready. `UNDEPLOYED`: Not available.
target_model	string	The speech recognition model that uses this vocabulary.
vocabulary	array[object]	The vocabulary entries. See Hotword entry structure.

Show Example

Request

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "query_vocabulary",
    "vocabulary_id": "vocab-testpfx-xxxx"
  }
}'

Response

{
  "output": {
    "gmt_create": "2025-12-19 11:47:11",
    "gmt_modified": "2025-12-19 11:47:11",
    "status": "OK",
    "target_model": "fun-asr",
    "vocabulary": [
      {
        "lang": "en",
        "text": "Seediq Bale",
        "weight": 4
      }
    ]
  },
  "usage": {
    "count": 1
  },
  "request_id": "3d461d3f-b2c4-4de5-xxxx"
}

Update a vocabulary

Request body

Parameter	Type	Required	Description
model	string	Yes	Set to `speech-biasing`.
input	object	Yes	The input parameters. See below.

Show input properties

Parameter	Type	Required	Description
action	string	Yes	The operation type. Set to `update_vocabulary`.
vocabulary_id	string	Yes	The ID of the vocabulary to update.
vocabulary	array[object]	Yes	The new vocabulary. This completely replaces the existing entries. See Hotword entry structure.

Response body

Parameter	Type	Description
request_id	string	The unique identifier of this request.
output	object	The response data. Always empty.
usage	object	Usage information.
usage.count	integer	The number of vocabularies updated. Always 1.

Show Example

Request

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "update_vocabulary",
    "vocabulary_id": "vocab-testpfx-xxx",
    "vocabulary": [
      {"text": "Seediq Bale", "weight": 4, "lang": "en"}
    ]
  }
}'

Response

{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

Delete a vocabulary

Request body

Parameter	Type	Required	Description
model	string	Yes	Set to `speech-biasing`.
input	object	Yes	The input parameters. See below.

Show input properties

Parameter	Type	Required	Description
action	string	Yes	The operation type. Set to `delete_vocabulary`.
vocabulary_id	string	Yes	The ID of the vocabulary to delete.

Response body

Parameter	Type	Description
request_id	string	The unique identifier of this request.
output	object	The response data. Always empty.
usage	object	Usage information.
usage.count	integer	The number of vocabularies deleted. Always 1.

Show Example

Request

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "delete_vocabulary",
    "vocabulary_id": "vocab-testpfx-xxx"
  }
}'

Response

{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

Hotword entry structure

Each entry in the vocabulary array has the following fields:

Field	Type	Required	Description
text	string	Yes	The vocabulary entry text. The text language must be supported by the selected model. Use actual words rather than arbitrary character combinations. Maximum length: 15 characters for text that includes non-ASCII characters, or 7 space-separated words for ASCII-only text.
weight	integer	Yes	The vocabulary entry weight. Recommended value: 4. Valid values: 1 to 5. If recognition accuracy doesn't improve, increase the weight. An excessively high weight may reduce the recognition accuracy of other words.
lang	string	No	The language code of the audio to be recognized. When set, the system improves recognition of vocabulary entries in the specified language. If you can't determine the language in advance, leave this parameter unset. Valid values vary by model. Fun-ASR: `zh` (Chinese), `en` (English), `ja` (Japanese).

​Prerequisites

​Endpoint

​Request headers

​Create a vocabulary

​Request body

​Response body

​List vocabularies

​Request body

​Response body

​Get a vocabulary

​Request body

​Response body

​Update a vocabulary

​Request body

​Response body

​Delete a vocabulary

​Request body

​Response body

​Hotword entry structure

Prerequisites

Endpoint

Request headers

Create a vocabulary

Request body

Response body

List vocabularies

Request body

Response body

Get a vocabulary

Request body

Response body

Update a vocabulary

Request body

Response body

Delete a vocabulary

Request body

Response body

Hotword entry structure