Custom hotwords Python SDK reference-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

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

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.

User guide: Improve recognition accuracy.

Important

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

Endpoint

The SDK connects to the China (Beijing) endpoint by default. To use a different region, set dashscope.base_http_api_url before making any API calls.

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.

To use the Singapore region, set dashscope.base_http_api_url before making any calls:

import dashscope

# Set this at the beginning of your code
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

Note:

API keys differ across regions. Use the API key that matches your region.
The region setting is global and affects all DashScope API calls.

VocabularyService

Package: dashscope.audio.asr.VocabularyService

Description: Creates, lists, queries, updates, and deletes custom vocabularies.

Constructor

VocabularyService(api_key: str = None, workspace: str = None, model: str = None)

If api_key is not passed, the SDK uses the global dashscope.api_key.

create_vocabulary() - Create a custom vocabulary

Method signature:

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

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 text, weight, and lang. For more information, see Hotword dictionary structure.

Return value:

Type	Description
str	The ID of the created vocabulary.

list_vocabularies() - List custom vocabularies

Maps to the HTTP API action: list_vocabulary (HTTP uses the singular form, while the Python method name list_vocabularies uses the plural).

Method signature:

def list_vocabularies(
    self,
    prefix: str = None,
    page_index: int = 0,
    page_size: int = 10) -> List[dict]

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
List[dict]	A list of vocabulary objects, each containing vocabulary_id, gmt_create, gmt_modified, and status.

Fields returned by list_vocabularies():

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.

query_vocabulary() - Query a custom vocabulary

Method signature:

def query_vocabulary(
    self,
    vocabulary_id: str) -> dict

Parameters:

Parameter	Type	Required	Description
vocabulary_id	str	Yes	The ID of the custom vocabulary to query.

Return value:

Type	Description
dict	A vocabulary object containing vocabulary, target_model, gmt_create, gmt_modified, and status.

Fields returned by query_vocabulary():

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_vocabulary() - Update a custom vocabulary

Method signature:

def update_vocabulary(
    self,
    vocabulary_id: str,
    vocabulary: List[dict]) -> None

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: None

delete_vocabulary() - Delete a custom vocabulary

Method signature:

def delete_vocabulary(
    self,
    vocabulary_id: str) -> None

Parameters:

Parameter	Type	Required	Description
vocabulary_id	str	Yes	The ID of the vocabulary to delete.

Return value: None

Hotword dictionary structure

Fields in each vocabulary dict:

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

All examples read the API key from an environment variable.

Create a custom vocabulary

import dashscope
from dashscope.audio.asr import *
import os

# 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: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following URL is for the China (Beijing) region. The URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

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

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

# Create a custom vocabulary
service = VocabularyService()
vocabulary_id = service.create_vocabulary(
    prefix=prefix,
    target_model=target_model,
    vocabulary=my_vocabulary)

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

List custom vocabularies

import dashscope
from dashscope.audio.asr import *
import json
import os

# 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: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following URL is for the China (Beijing) region. The URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

service = VocabularyService()
vocabularies = service.list_vocabularies()
print(f"Vocabularies: {json.dumps(vocabularies)}")

Query a custom vocabulary

import dashscope
from dashscope.audio.asr import *
import json
import os

# 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: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following URL is for the China (Beijing) region. The URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

service = VocabularyService()
# Replace with the actual vocabulary ID when querying
vocabulary = service.query_vocabulary("vocab-testpfx-xxx")
print(f"Vocabulary: {json.dumps(vocabulary)}")

Update a custom vocabulary

import dashscope
from dashscope.audio.asr import *
import os

# 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: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following URL is for the China (Beijing) region. The URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

service = VocabularyService()
my_vocabulary = [
    {"text": "Seediq Bale", "weight": 4, "lang": "en"}
]
# Replace with the actual vocabulary ID when updating
service.update_vocabulary("vocab-testpfx-xxx", my_vocabulary)

Delete a custom vocabulary

import dashscope
from dashscope.audio.asr import *
import os

# 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: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following URL is for the China (Beijing) region. The URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

service = VocabularyService()
# Replace with the actual vocabulary ID when deleting
service.delete_vocabulary("vocab-testpfx-xxxx")