DocsICP FilingConsole
官方文档
首页

Custom vocabulary HTTP API reference

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

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

User guide: Improve recognition accuracy.

Important

Custom vocabulary isn't supported in sub-workspaces of the Singapore region.

Endpoint

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/customization

Replace {WorkspaceId} with your actual workspace ID.

Singapore

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

Replace {WorkspaceId} with your actual Workspace ID.

Important

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

The following URL is for the China (Beijing) region. 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}.cn-beijing.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}
        ]
    }
}'

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:

    • zh: Chinese

    • en: English

    • ja: Japanese

    • yue: Cantonese

    • ko: Korean

    • de: German

    • fr: French

    • ru: Russian

  • Fun-ASR:

    • zh: Chinese

    • en: English

    • ja: Japanese

Response body

 
{
    "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 China (Beijing) region. 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}.cn-beijing.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
    }
}'

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

 
{
    "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 China (Beijing) region. 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}.cn-beijing.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"
    }
}'

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

 
{
  "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 China (Beijing) region. 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}.cn-beijing.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"}
        ]
    }
}'

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:

    • zh: Chinese

    • en: English

    • ja: Japanese

    • yue: Cantonese

    • ko: Korean

    • de: German

    • fr: French

    • ru: Russian

  • Fun-ASR:

    • zh: Chinese

    • en: English

    • ja: Japanese

Response body

 
{
  "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 China (Beijing) region. 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}.cn-beijing.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"
    }
}'

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

 
{
  "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.
Previous：Custom hotwordsNext：Python SDK reference