Custom hotwords Python SDK reference

Use the Python SDK to create, list, query, update, and delete custom vocabularies for speech recognition. User guide: Custom hotwords. Important

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

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.

International

If you select the International deployment scope, model inference compute resources are dynamically scheduled worldwide, excluding the Chinese mainland. Static data is stored in your selected region. Supported region: Singapore.

https://dashscope-intl.aliyuncs.com/api/v1

Chinese mainland

If you select the Chinese mainland deployment scope, model inference compute resources are restricted to the Chinese mainland. Static data is stored in your selected region. Supported region: China (Beijing).

https://dashscope.aliyuncs.com/api/v1

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

HELPCODEESCAPE-python
import dashscope


dashscope.base_http_api_url = 'https://dashscope-intl.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

HELPCODEESCAPE-python
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:

HELPCODEESCAPE-python
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:

HELPCODEESCAPE-python
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:

HELPCODEESCAPE-python
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:

HELPCODEESCAPE-python
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:

HELPCODEESCAPE-python
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

HELPCODEESCAPE-python
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://www.alibabacloud.com/help/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 Singapore region. To use the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.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

HELPCODEESCAPE-python
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://www.alibabacloud.com/help/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 Singapore region. To use the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

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

Query a custom vocabulary

HELPCODEESCAPE-python
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://www.alibabacloud.com/help/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 Singapore region. To use the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.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, ensure_ascii=False)}")

Update a custom vocabulary

HELPCODEESCAPE-python
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://www.alibabacloud.com/help/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 Singapore region. To use the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.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

HELPCODEESCAPE-python
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://www.alibabacloud.com/help/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 Singapore region. To use the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

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

Custom hotwords Python SDK reference ​

Endpoint ​

International ​

Chinese mainland ​

VocabularyService ​

Constructor ​

create_vocabulary() - Create a custom vocabulary ​

list_vocabularies() - List custom vocabularies ​

query_vocabulary() - Query a custom vocabulary ​

update_vocabulary() - Update a custom vocabulary ​

delete_vocabulary() - Delete a custom vocabulary ​

Hotword dictionary structure ​

Sample code ​

Create a custom vocabulary ​

List custom vocabularies ​

Query a custom vocabulary ​

Update a custom vocabulary ​

Delete a custom vocabulary ​

Custom hotwords Python SDK reference

Endpoint

International

Chinese mainland

VocabularyService

Constructor

create_vocabulary() - Create a custom vocabulary

list_vocabularies() - List custom vocabularies

query_vocabulary() - Query a custom vocabulary

update_vocabulary() - Update a custom vocabulary

delete_vocabulary() - Delete a custom vocabulary

Hotword dictionary structure

Sample code

Create a custom vocabulary

List custom vocabularies

Query a custom vocabulary

Update a custom vocabulary

Delete a custom vocabulary