custom vocabulary HTTP API reference - Alibaba Cloud Model Studio

Manage custom vocabularies through HTTP APIs, including creating, listing, getting, updating, and deleting vocabularies.

User guide: Improve recognition accuracy.

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

Endpoint

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/customization

Replace {WorkspaceId} with your actual Workspace ID.

China (Beijing)

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/customization

Replace {WorkspaceId} with your actual workspace ID.

ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

China (Beijing): from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token. Use the format `Bearer <api_key>`, where `<api_key>` is your API key.
Content-Type	string	Yes	Media type of the request body. Set to `application/json`.

Create a vocabulary

Request body

modelstring(Required)

The custom vocabulary model. Set to speech-biasing.

inputobject(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:
- zh: Chinese
- en: English
- ja: Japanese
- yue: Cantonese
- ko: Korean
- de: German
- fr: French
- ru: Russian
Fun-ASR:
- zh: Chinese
- en: English
- ja: Japanese

The following URL is for the Singapore region. Replace WorkspaceId with your actual workspace ID. The URLs vary by region.

The API keys for the Singapore region and the Beijing region are different. For more information, see Obtain an API key.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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 body

request_idstring

The unique identifier of this request.

outputobject

The response data.

Properties

vocabulary_idstring

The ID of the created vocabulary.

usageobject

The usage information of this request.

Properties

count integer

The number of vocabularies created. Always 1.

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

List vocabularies

Request body

modelstring(Required)

The custom vocabulary model. Set to speech-biasing.

inputobject(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.

The following URL is for the Singapore region. Replace WorkspaceId with your actual workspace ID. The URLs vary by region.

The API keys for the Singapore region and the Beijing region are different. For more information, see Obtain an API key.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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 body

request_idstring

The unique identifier of this request.

outputobject

The response data.

Properties

vocabulary_listarray[object]

The queried vocabularies.

Properties

vocabulary_idstring

The vocabulary ID.

gmt_createstring

The creation time.

gmt_modifiedstring

The last modification time.

statusstring

The status:

OK: Ready.
UNDEPLOYED: Not available.

usageobject

The usage information of this request.

Properties

count integer

Always 1.

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

modelstring(Required)

The custom vocabulary model. Set to speech-biasing.

inputobject(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.

The following URL is for the Singapore region. Replace WorkspaceId with your actual workspace ID. The URLs vary by region.

The API keys for the Singapore region and the Beijing region are different. For more information, see Obtain an API key.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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 body

request_idstring

The unique identifier of this request.

outputobject

The response data.

Properties

gmt_createstring

The creation time.

gmt_modifiedstring

The last modification time.

statusstring

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.

vocabularyarray[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.

usageobject

The usage information of this request.

Properties

count integer

Always 1.

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

modelstring(Required)

The custom vocabulary model. Set to speech-biasing.

inputobject(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)

Valid values (vary by model):

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

The following URL is for the Singapore region. Replace WorkspaceId with your actual workspace ID. The URLs vary by region.

The API keys for the Singapore region and the Beijing region are different. For more information, see Obtain an API key.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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 body

request_idstring

The unique identifier of this request.

outputobject

The response data. Always empty.

usageobject

The usage information of this request.

Properties

count integer

The number of vocabularies updated. Always 1.

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

Delete a vocabulary

Request body

modelstring(Required)

The custom vocabulary model. Set to speech-biasing.

inputobject(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.

The following URL is for the Singapore region. Replace WorkspaceId with your actual workspace ID. The URLs vary by region.

The API keys for the Singapore region and the Beijing region are different. For more information, see Obtain an API key.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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 body

request_idstring

The unique identifier of this request.

outputobject

The response data. Always empty.

usageobject

The usage information of this request.

Properties

count integer

The number of vocabularies deleted. Always 1.

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