Custom hotwords Python SDK

Prerequisites

An API key configured as the DASHSCOPE_API_KEY environment variable
The latest DashScope SDK

Service URL

Set the base URL before creating the service:

import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

VocabularyService class

Package: dashscope.audio.asr.VocabularyService Manages the lifecycle of custom vocabularies (create, list, query, update, delete).

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.

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

Parameter	Type	Required	Description
target_model	str	Yes	The speech recognition model that uses this vocabulary. 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, max 10 characters.
vocabulary	List[dict]	Yes	A list of hotwords. See Hotword entry structure.

Returns: str — the ID of the created vocabulary.

Show Example

import dashscope
from dashscope.audio.asr import VocabularyService
import os

dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
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}
]

service = VocabularyService()
vocabulary_id = service.create_vocabulary(
  prefix=prefix,
  target_model=target_model,
  vocabulary=my_vocabulary)

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

list_vocabularies()

List custom vocabularies with optional filtering and pagination.

The HTTP API uses the singular form list_vocabulary, while the Python method name uses the plural list_vocabularies.

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

Parameter	Type	Required	Description
prefix	str	No	Filter by vocabulary prefix.
page_index	int	No	Page number, starting from 0. Default: 0.
page_size	int	No	Number of entries per page. Default: 10.

Returns: List[dict] — a list of vocabulary objects, each containing:

Field	Type	Description
vocabulary_id	str	The vocabulary ID.
gmt_create	str	The creation time.
gmt_modified	str	The last modification time.
status	str	`OK`: Ready. `UNDEPLOYED`: Not available.

Show Example

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

dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
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_vocabulary()

Query details of a specific custom vocabulary.

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

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

Returns: dict — a vocabulary object containing:

Field	Type	Description
vocabulary	List[dict]	The hotword list content.
target_model	str	The speech recognition model that uses this vocabulary.
gmt_create	str	The creation time.
gmt_modified	str	The last modification time.
status	str	`OK`: Ready. `UNDEPLOYED`: Not available.

Show Example

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

dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

service = VocabularyService()
vocabulary = service.query_vocabulary("vocab-testpfx-xxx")
print(f"Vocabulary: {json.dumps(vocabulary, ensure_ascii=False)}")

update_vocabulary()

Update a custom vocabulary. This completely replaces the existing entries.

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

Parameter	Type	Required	Description
vocabulary_id	str	Yes	The ID of the vocabulary to update.
vocabulary	List[dict]	Yes	The new vocabulary entries. See Hotword entry structure.

Returns: None

Show Example

import dashscope
from dashscope.audio.asr import VocabularyService
import os

dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

service = VocabularyService()
my_vocabulary = [
  {"text": "Seediq Bale", "weight": 4, "lang": "en"}
]
service.update_vocabulary("vocab-testpfx-xxx", my_vocabulary)

delete_vocabulary()

Delete a custom vocabulary.

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

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

Returns: None

Show Example

import dashscope
from dashscope.audio.asr import VocabularyService
import os

dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

service = VocabularyService()
service.delete_vocabulary("vocab-testpfx-xxxx")

Hotword entry structure

Each entry in the vocabulary list has the following fields:

Field	Type	Required	Description
text	str	Yes	The vocabulary entry text. The text language must be supported by the selected model. Use actual words rather than arbitrary character combinations. 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. Valid values vary by model. Fun-ASR: `zh` (Chinese), `en` (English), `ja` (Japanese).

​Prerequisites

​Service URL

​VocabularyService class

​Constructor

​create_vocabulary()

​list_vocabularies()

​query_vocabulary()

​update_vocabulary()

​delete_vocabulary()

​Hotword entry structure

Prerequisites

Service URL

VocabularyService class

Constructor

create_vocabulary()

list_vocabularies()

query_vocabulary()

update_vocabulary()

delete_vocabulary()

Hotword entry structure