Custom hotwords Python SDK reference

Updated at:

Use the Python SDK to create, list, query, update, and delete custom vocabularies for speech recognition.

User guide: Improve recognition accuracy. For usage limits such as the maximum number of vocabulary lists, see hotword limits and billing.

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

Endpoint

The SDK uses the China (Beijing) endpoint by default. To switch to a different region, specify the region parameter when constructing dashscope.Client (for example, ap-southeast-1 for the Singapore region).

China (Beijing)

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

Replace {WorkspaceId} with your actual workspace ID.

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

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.

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.

Switch to the Singapore region:

import os
import dashscope

# Specify the Singapore region when constructing the client
client = dashscope.Client(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    region='ap-southeast-1',
)
Note:
  • API keys differ across regions. Use the API key that matches your region.
  • The region is a per-instance setting on dashscope.Client and only affects the API calls made by that client.

client.audio.vocabularies

Resource entry: the client.audio.vocabularies resource on a dashscope.Client instance

Description: Manages the lifecycle of custom vocabularies (create, list, query, update, and delete).

Construction

import os
import dashscope

client = dashscope.Client(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace='{WorkspaceId}',
    region='cn-beijing',
)

If api_key is not passed, the SDK automatically reads the DASHSCOPE_API_KEY environment variable.

create() - Create a custom vocabulary

Method signature:

def create(
    self,
    *,
    target_model: str,
    prefix: str,
    vocabulary: List[dict]) -> Vocabulary

Parameters:

Parameter

Type

Required

Description

target_model

str

Yes

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

prefix

str

Yes

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

vocabulary

List[dict]

Yes

A list of hotwords. Each entry is a dict with fields such as text, weight, and lang.

For more information, see Hotword dictionary structure.

Return value:

Type

Description

Vocabulary

The vocabulary object. Use the vocabulary_id field to get the vocabulary ID.

list() - List custom vocabularies

Maps to the HTTP API action: list_vocabulary.

Method signature:

def list(
    self,
    *,
    prefix: str = None,
    page_index: int = 0,
    page_size: int = 10) -> VocabularyList

Parameters:

Parameter

Type

Required

Description

prefix

str

No

The custom prefix of the vocabulary. When specified, only vocabularies with this prefix are returned.

page_index

int

No

The page number, starting from 0.

Default value: 0.

page_size

int

No

The number of entries per page.

Default value: 10.

Return value:

Type

Description

VocabularyList

A paginated vocabulary list object. The vocabularies field is an array of vocabulary entries, each containing vocabulary_id, gmt_create, gmt_modified, and status.

Fields of the returned object:

Field

Type

Description

vocabulary_id

str

The vocabulary ID.

gmt_create

str

The creation time.

gmt_modified

str

The last modification time.

status

str

The status:

  • OK: Ready.

  • UNDEPLOYED: Not available.


get() - Query a custom vocabulary

Maps to query_vocabulary() in the 1.x SDK.

Method signature:

def get(
    self,
    vocabulary_id: str) -> Vocabulary

Parameters:

Parameter

Type

Required

Description

vocabulary_id

str

Yes

The ID of the custom vocabulary to query.

Return value:

Type

Description

Vocabulary

A vocabulary detail object containing vocabulary, target_model, gmt_create, gmt_modified, and status.

Fields of the returned object:

Field

Type

Description

vocabulary

List[dict]

The hotword list content.

target_model

str

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

gmt_create

str

The creation time.

gmt_modified

str

The last modification time.

status

str

The status:

  • OK: Ready.

  • UNDEPLOYED: Not available.

update() - Update a custom vocabulary

Method signature:

def update(
    self,
    vocabulary_id: str,
    *,
    vocabulary: List[dict]) -> JobStatus

Parameters:

Parameter

Type

Required

Description

vocabulary_id

str

Yes

The ID of the vocabulary to update.

vocabulary

List[dict]

Yes

The new vocabulary. This completely replaces the existing entries.

Return value: A JobStatus object. The status field indicates the operation status.

delete() - Delete a custom vocabulary

Method signature:

def delete(
    self,
    vocabulary_id: str) -> JobStatus

Parameters:

Parameter

Type

Required

Description

vocabulary_id

str

Yes

The ID of the vocabulary to delete.

Return value: A JobStatus object. The status field indicates the operation status.

Hotword dictionary structure

Dictionary definition for the vocabulary parameter:

Field

Type

Required

Description

text

str

Yes

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

int

Yes

The vocabulary entry weight. Commonly used 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

str

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

Sample code

Create a custom vocabulary

import os
import dashscope

# The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. Configurations vary by region.
    workspace='{WorkspaceId}',
    region='cn-beijing',
)

prefix = 'testpfx'
target_model = "fun-asr"

my_vocabulary = [
    {"text": "Seediq Bale", "weight": 4}
]

# Create a custom vocabulary
vocabulary = client.audio.vocabularies.create(
    prefix=prefix,
    target_model=target_model,
    vocabulary=my_vocabulary)

print(f"Vocabulary ID: {vocabulary.vocabulary_id}")

List custom vocabularies

import json
import os
import dashscope

# The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. Configurations vary by region.
    workspace='{WorkspaceId}',
    region='cn-beijing',
)

result = client.audio.vocabularies.list()
print(f"Vocabularies: {json.dumps(result.vocabularies)}")

Query a custom vocabulary

import json
import os
import dashscope

# The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. Configurations vary by region.
    workspace='{WorkspaceId}',
    region='cn-beijing',
)

# Replace with the actual vocabulary ID when querying
vocabulary = client.audio.vocabularies.get("vocab-testpfx-xxx")
print(f"Vocabulary: {json.dumps(vocabulary.vocabulary)}")

Update a custom vocabulary

import os
import dashscope

# The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. Configurations vary by region.
    workspace='{WorkspaceId}',
    region='cn-beijing',
)

my_vocabulary = [
    {"text": "Seediq Bale", "weight": 4, "lang": "en"}
]
# Replace with the actual vocabulary ID when updating
result = client.audio.vocabularies.update("vocab-testpfx-xxx", vocabulary=my_vocabulary)
print(f"Update status: {result.status}")

Delete a custom vocabulary

import os
import dashscope

# The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. Configurations vary by region.
    workspace='{WorkspaceId}',
    region='cn-beijing',
)

# Replace with the actual vocabulary ID when deleting
result = client.audio.vocabularies.delete("vocab-testpfx-xxxx")
print(f"Delete status: {result.status}")