Alibaba AI Docs

Appearance

Custom vocabulary HTTP API reference ​

Manage custom vocabularies through HTTP APIs, including creating, listing, getting, updating, and deleting vocabularies. User guide: Custom hotwords. Important

Custom vocabulary is supported only in the primary workspace. Sub-workspaces don't support it.

Endpoint ​

International ​

If you select the International deployment scope, model inference compute resources are dynamically scheduled worldwide, excluding the Chinese mainland. Static data is stored in your selected region. Supported region: Singapore.

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

Chinese mainland ​

If you select the Chinese mainland deployment scope, model inference compute resources are restricted to the Chinese mainland. Static data is stored in your selected region. Supported region: China (Beijing).

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

Request headers ​

ParameterTypeRequiredDescription
AuthorizationstringYesBearer token. Use the format Bearer , where is your API key.
Content-TypestringYesMedia type of the request body. Set to application/json.

Create a vocabulary ​

Request body ​

The following URL is for the Singapore region. To use a model deployed in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization. The API keys for the Singapore region and the Beijing region are different. For more information, see Create an API key.

curl
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}
 \]
 }
}'
   **model **`*string*`* ***(Required)**

The custom vocabulary model. Set to speech-biasing.

**input **object* *(Required) The input parameters. Properties

action *string** *(Required) The operation type. Set to create_vocabulary.

target_model *string** *(Required) The speech recognition model that uses this vocabulary. This value must match the model you specify when calling the speech recognition API.

prefix *string** *(Required) A custom prefix for the vocabulary. Only lowercase letters and digits are allowed, with a maximum length of 10 characters.

vocabulary *array\[object\]** *(Required) The vocabulary entries array. Properties

text *string** *(Required) The vocabulary entry text. The text language must be supported by the selected model. Supported languages vary by model. Use actual words rather than arbitrary character combinations to improve recognition accuracy. Maximum length: 15 characters for text that includes non-ASCII characters, or 7 space-separated words for ASCII-only text.

weight *integer** *(Required) 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** *(Optional) 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. The model detects the language automatically. Valid values (vary by model):

  • Paraformer: <li>zh: Chinese
  • en: English
  • ja: Japanese
  • yue: Cantonese
  • ko: Korean
  • de: German
  • fr: French
  • ru: Russian </li>
  • Fun-ASR: <li>zh: Chinese
  • en: English
  • ja: Japanese </li>

Response body ​

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

**request_id ***string* The unique identifier of this request.

**output ***object* The response data. Properties

**vocabulary_id ***string* The ID of the created vocabulary.

**usage ***object* The usage information of this request. Properties

count *integer* The number of vocabularies created. Always 1.

List vocabularies ​

Request body ​

The following URL is for the Singapore region. To use a model deployed in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization. The API keys for the Singapore region and the Beijing region are different. For more information, see Create an API key.

curl
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
 }
}'
   **model **`*string*`* ***(Required)**

The custom vocabulary model. Set to speech-biasing.

**input **object* *(Required) The input parameters. Properties

action *string** *(Required) The operation type. Set to list_vocabulary.

prefix *string** *(Optional) The custom prefix of the vocabulary. When specified, only vocabularies with this prefix are returned.

page_index *integer* The page number, starting from 0. Default value: 0.

page_size *integer* The number of entries per page. Default value: 10.

Response body ​

json
{
 "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"
}

**request_id ***string* The unique identifier of this request.

**output ***object* The response data. Properties

**vocabulary_list ***array\[object\]* The queried vocabularies. Properties

**vocabulary_id ***string* The vocabulary ID.

**gmt_create ***string* The creation time.

**gmt_modified ***string* The last modification time.

**status ***string* The status:

  • OK: Ready.
  • UNDEPLOYED: Not available.

**usage ***object* The usage information of this request. Properties

count *integer* Always 1.

Get a vocabulary ​

Request body ​

The following URL is for the Singapore region. To use a model deployed in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization. The API keys for the Singapore region and the Beijing region are different. For more information, see Create an API key.

curl
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"
 }
}'
   **model **`*string*`* ***(Required)**

The custom vocabulary model. Set to speech-biasing.

**input **object* *(Required) The input parameters. Properties

action *string** *(Required) The operation type. Set to query_vocabulary.

vocabulary_id *string** *(Required) The ID of the vocabulary to get.

Response body ​

json
{
 "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"
}

**request_id ***string* The unique identifier of this request.

**output ***object* The response data. Properties

**gmt_create ***string* The creation time.

**gmt_modified ***string* The last modification time.

**status ***string* The status:

  • OK: Ready.
  • UNDEPLOYED: Not available.

target_model *string*

The speech recognition model that uses this vocabulary. This value must match the model you specify when calling the speech recognition API.

**vocabulary ***array\[object\]* The queried vocabulary. Properties

text *string* The vocabulary entry text.

weight *integer* The vocabulary entry weight.

lang *string* The language of the audio to be recognized.

**usage ***object* The usage information of this request. Properties

count *integer* Always 1.

Update a vocabulary ​

Request body ​

The following URL is for the Singapore region. To use a model deployed in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization. The API keys for the Singapore region and the Beijing region are different. For more information, see Create an API key.

curl
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"}
 \]
 }
}'
   **model **`*string*`* ***(Required)**

The custom vocabulary model. Set to speech-biasing.

**input **object* *(Required) The input parameters. Properties

action *string** *(Required) The operation type. Set to update_vocabulary.

vocabulary_id *string** *(Required) The ID of the vocabulary to update.

vocabulary *array\[object\]** *(Required) The new vocabulary. This completely replaces the existing entries.

Properties

text *string** *(Required) The vocabulary entry text. The text language must be supported by the selected model. Supported languages vary by model. Use actual words rather than arbitrary character combinations to improve recognition accuracy. Maximum length: 15 characters for text that includes non-ASCII characters, or 7 space-separated words for ASCII-only text.

weight *integer** *(Required) 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** *(Optional) 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. The model detects the language automatically. Valid values (vary by model):

  • Paraformer: <li>zh: Chinese
  • en: English
  • ja: Japanese
  • yue: Cantonese
  • ko: Korean
  • de: German
  • fr: French
  • ru: Russian </li>
  • Fun-ASR: <li>zh: Chinese
  • en: English
  • ja: Japanese </li>

Response body ​

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

**request_id ***string* The unique identifier of this request.

**output ***object* The response data. Always empty.

**usage ***object* The usage information of this request. Properties

count *integer* The number of vocabularies updated. Always 1.

Delete a vocabulary ​

Request body ​

The following URL is for the Singapore region. To use a model deployed in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization. The API keys for the Singapore region and the Beijing region are different. For more information, see Create an API key.

curl
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"
 }
}'
   **model **`*string*`* ***(Required)**

The custom vocabulary model. Set to speech-biasing.

**input **object* *(Required) The input parameters. Properties

action *string** *(Required) The operation type. Set to delete_vocabulary.

vocabulary_id *string** *(Required) The ID of the vocabulary to delete.

Response body ​

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

**request_id ***string* The unique identifier of this request.

**output ***object* The response data. Always empty.

**usage ***object* The usage information of this request. Properties

count *integer* The number of vocabularies deleted. Always 1.

Mirror of Alibaba Cloud Model Studio docs for reference and RAG. Not affiliated with Alibaba Cloud.

Source: alibabacloud.com/help/en/model-studio