Custom vocabulary HTTP API reference - Alibaba Cloud Model Studio

User guide: Improve recognition accuracy.

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

Endpoint

Singapore
China (Beijing)

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/customizationReplace {WorkspaceId} with your actual Workspace ID.

Alibaba 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_idstringThe unique identifier of this request.outputobjectThe response data.

Properties

vocabulary_idstringThe ID of the created vocabulary.

usageobjectThe usage information of this request.

Properties

count integerThe 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 integerThe page number, starting from 0.Default value: 0.page_size integerThe number of entries per page.Default value: 10.

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_idstringThe unique identifier of this request.outputobjectThe response data.

Properties

vocabulary_listarray[object]The queried vocabularies.

Properties

vocabulary_idstringThe vocabulary ID.gmt_createstringThe creation time.gmt_modifiedstringThe last modification time.statusstringThe status:

OK: Ready.
UNDEPLOYED: Not available.

usageobjectThe usage information of this request.

Properties

count integerAlways 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.

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_idstringThe unique identifier of this request.outputobjectThe response data.

Properties

gmt_createstringThe creation time.gmt_modifiedstringThe last modification time.statusstringThe status:

OK: Ready.
UNDEPLOYED: Not available.

target_model stringThe 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 stringThe vocabulary entry text.weight integerThe vocabulary entry weight.lang stringThe language of the audio to be recognized.

usageobjectThe usage information of this request.

Properties

count integerAlways 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

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

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_idstringThe unique identifier of this request.outputobjectThe response data. Always empty.usageobjectThe usage information of this request.

Properties

count integerThe 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.

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_idstringThe unique identifier of this request.outputobjectThe response data. Always empty.usageobjectThe usage information of this request.

Properties

count integerThe number of vocabularies deleted. Always 1.

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

​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

Endpoint

Request headers

Create a vocabulary

List vocabularies

Get a vocabulary

Update a vocabulary

Delete a vocabulary