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

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

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

ImportantCustom vocabularies aren't supported in sub-workspaces of the Singapore region.

Endpoint

The SDK uses the China (Beijing) endpoint by default. To switch to another region, modify Constants.baseHttpApiUrl before initialization.

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, which 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 com.alibaba.dashscope.utils.Constants;

// 在代码开头设置
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Note:

API keys differ across regions. Make sure you use the API key of the corresponding region.
The region setting is a global setting that affects all API calls made by DashScope SDKs.

VocabularyService

Package path: com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService

Description: Manages the lifecycle of custom vocabularies (creation, query, update, and deletion).

Constructor

public VocabularyService(String apiKey)

Parameters:

Parameter	Type	Description
apiKey	String	DashScope API key

createVocabulary() - Create a custom vocabulary

Method signature:

public Vocabulary createVocabulary(String targetModel,String prefix,JsonArray vocabulary) throws NoApiKeyException, InputRequiredException

Parameters:

Parameter	Type	Required	Description
targetModel	String	Yes	The speech recognition model that uses this vocabulary. This value must match the model you specify when calling the speech recognition API.
prefix	String	Yes	A custom prefix for the vocabulary. Only digits and lowercase letters are allowed, with a maximum length of 10 characters.
vocabulary	JsonArray	Yes	The list of hotwords. Each JsonObject contains fields such as text, weight, and lang. For more information, see Hotword object structure.

Parameter

Type

Required

Description

targetModel

String

Yes

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

prefix

String

Yes

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

vocabulary

JsonArray

Yes

The list of hotwords. Each JsonObject contains fields such as text, weight, and lang.

For more information, see Hotword object structure.

Return value:

Type	Description
Vocabulary	A custom vocabulary object that contains information such as the vocabulary ID.

Exceptions:

Exception	Description
NoApiKeyException	The API key is empty.
InputRequiredException	A required parameter is empty.

listVocabulary() - List custom vocabularies

Method signature:

public Vocabulary[] listVocabulary(String prefix) throws NoApiKeyException, InputRequiredException

public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

Parameters:

Parameter	Type	Required	Description
prefix	String	No	The custom prefix of the vocabulary. When specified, only vocabularies with the specified prefix are returned.
pageIndex	int	No	The page index, starting from 0. Default value: 0.
pageSize	int	No	The number of entries per page. Default value: 10.

Return value:

Type	Description
Vocabulary[]	An array of custom vocabulary objects.

Vocabulary object fields (returned by list):

Field	Type	Description
vocabularyId	String	The vocabulary ID.
gmtCreate	String	The creation time.
gmtModified	String	The last modification time.
status	String	The status: OK: Available. UNDEPLOYED: Not available.

Exceptions:

Exception	Description
NoApiKeyException	The API key is empty.
InputRequiredException	A required parameter is empty.

queryVocabulary() - Query a custom vocabulary

Method signature:

public Vocabulary queryVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

Parameters:

Parameter	Type	Required	Description
vocabularyId	String	Yes	The ID of the custom vocabulary to query.

Return value:

Type	Description
Vocabulary	A custom vocabulary object that contains detailed information.

Vocabulary object fields (returned by query):

Field	Type	Description
vocabulary	JsonArray	The custom vocabulary content.
targetModel	String	The speech recognition model that uses this vocabulary. This value must match the model you specify when calling the speech recognition API.
gmtCreate	String	The creation time.
gmtModified	String	The last modification time.
status	String	The status: OK: Available. UNDEPLOYED: Not available.

Exceptions:

Exception	Description
NoApiKeyException	The API key is empty.
InputRequiredException	A required parameter is empty.

updateVocabulary() - Update a custom vocabulary

Method signature:

public void updateVocabulary(String vocabularyId,JsonArray vocabulary) throws NoApiKeyException, InputRequiredException

Parameters:

Parameter	Type	Required	Description
vocabularyId	String	Yes	The ID of the custom vocabulary to update.
vocabulary	JsonArray	Yes	The new custom vocabulary, which completely replaces the existing content.

Return value: None

Exceptions:

Exception	Description
NoApiKeyException	The API key is empty.
InputRequiredException	A required parameter is empty.

deleteVocabulary() - Delete a custom vocabulary

Method signature:

public void deleteVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

Parameters:

Parameter	Type	Required	Description
vocabularyId	String	Yes	The ID of the custom vocabulary to delete.

Return value: None

Exceptions:

Exception	Description
NoApiKeyException	The API key is empty.
InputRequiredException	A required parameter is empty.

Vocabulary class

Package path: com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary

Description: A custom vocabulary object that encapsulates the metadata and content of the vocabulary.

Methods

Method	Return type	Description
getVocabularyId()	String	Returns the vocabulary ID.
getTargetModel()	String	Returns the target model.
getVocabulary()	JsonArray	Returns the custom vocabulary content.
getStatus()	String	Returns the status.
getGmtCreate()	String	Returns the creation time.
getGmtModified()	String	Returns the last modified time.
getData()	JsonObject	Returns the complete data in JSON format.

Hotword object structure

Definition of the JsonObject used for the vocabulary parameter:

Field	Type	Required	Description
text	String	Yes	The vocabulary entry text. The text language must be supported by the selected model. Supported languages vary by model. Hotwords are used to improve recognition accuracy. 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. Common value: 4. Valid values: 1 to 5. If the effect isn't obvious, you can increase the weight appropriately, but an excessively high weight may have negative effects and reduce the recognition accuracy of other words.
lang	String	No	The language code of the audio to be recognized. When set, the system enhances hotword recognition for the specified language. If you can't determine the language in advance, leave this parameter unset and 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 com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.util.ArrayList;
import java.util.List;

public class Main {
    // 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    // 若没有配置环境变量，请用百炼API Key将下行替换为：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        String targetModel = "fun-asr";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        wordList.add(new Hotword("吴贻弓", 4));
        wordList.add(new Hotword("阙里人家", 4));

        for (Hotword word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("weight", word.weight);
            vocabularyJson.add(jsonObject);
        }

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary vocabulary = service.createVocabulary(targetModel, "testpfx", vocabularyJson);
        System.out.println("热词列表ID：" + vocabulary.getVocabularyId());
    }
}

class Hotword {
    String text;
    int weight;

    public Hotword(String text, int weight) {
        this.text = text;
        this.weight = weight;
    }
}

List custom vocabularies

import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class Main {
    // 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    // 若没有配置环境变量，请用百炼API Key将下行替换为：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary[] vocabularies = service.listVocabulary("testpfx");
        Gson gson = new GsonBuilder()
                .setPrettyPrinting()
                .create();
        System.out.println("热词列表：" + gson.toJson(vocabularies));
    }
}

Query a custom vocabulary

import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class Main {
    // 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    // 若没有配置环境变量，请用百炼API Key将下行替换为：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        // 查询时替换为实际的热词列表ID
        Vocabulary vocabulary = service.queryVocabulary("vocab-testpfx-xxxx");
        Gson gson = new GsonBuilder()
                .setPrettyPrinting()
                .create();
        System.out.println("热词列表：" + gson.toJson(vocabulary.getData()));
    }
}

Update a custom vocabulary

import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.util.ArrayList;
import java.util.List;

public class Main {
    // 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    // 若没有配置环境变量，请用百炼API Key将下行替换为：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        wordList.add(new Hotword("吴贻弓", 4, "zh"));
        wordList.add(new Hotword("阙里人家", 4, "zh"));

        for (Hotword word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("weight", word.weight);
            jsonObject.addProperty("lang", word.lang);
            vocabularyJson.add(jsonObject);
        }

        VocabularyService service = new VocabularyService(apiKey);
        // 替换为实际的热词列表ID
        service.updateVocabulary("vocab-testpfx-xxx", vocabularyJson);
    }
}

class Hotword {
    String text;
    int weight;
    String lang;

    public Hotword(String text, int weight, String lang) {
        this.text = text;
        this.weight = weight;
        this.lang = lang;
    }
}

Delete a custom vocabulary

import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    // 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    // 若没有配置环境变量，请用百炼API Key将下行替换为：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        // 删除时替换为实际的热词列表ID
        service.deleteVocabulary("vocab-testpfx-xxxx");
    }
}