Custom hotwords Java SDK reference

Use the Java SDK to create, 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 uses the China (Beijing) endpoint by default. To switch to a different region, modify Constants.baseHttpApiUrl before initialization.

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 Constants.baseHttpApiUrl before initialization:

HELPCODEESCAPE-java
import com.alibaba.dashscope.common.Constants;

// Set this at the beginning of your code
Constants.baseHttpApiUrl = "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 : com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService

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

Constructor

HELPCODEESCAPE-java
public VocabularyService(String apiKey)

Parameters:

Parameter	Type	Description
apiKey	String	DashScope API key

createVocabulary() - Create a custom vocabulary

Method signature:

HELPCODEESCAPE-java
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 lowercase letters and digits 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 the vocabulary ID and other metadata.

Exceptions:

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

listVocabulary() - List custom vocabularies

Method signature:

HELPCODEESCAPE-java
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 this prefix are returned.
pageIndex	int	No	The page number, 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.

Fields returned by listVocabulary():

Field	Type	Description
vocabularyId	String	The vocabulary ID.
gmtCreate	String	The creation time.
gmtModified	String	The last modification time.
status	String	The status: - OK: Ready. - 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:

HELPCODEESCAPE-java
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 `Vocabulary` object with the hotword entries and metadata.

Fields returned by queryVocabulary():

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

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

Parameters:

Parameter	Type	Required	Description
vocabularyId	String	Yes	The ID of the vocabulary to update.
vocabulary	JsonArray	Yes	The new vocabulary. This completely replaces the existing entries.

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:

HELPCODEESCAPE-java
public void deleteVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

Parameters:

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

Return value: None

Exceptions:

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

Vocabulary class

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

Description: Stores the metadata and content of a custom 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

Fields in each hotword JsonObject:

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

HELPCODEESCAPE-java
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 {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio 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 {
        // The following is the URL for the Singapore region. If you are using a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        String targetModel = "fun-asr";

        JsonArray vocabularyJson = new JsonArray();
        List&lt;Hotword&gt; wordList = new ArrayList<>();
        wordList.add(new Hotword("Wu yi gong", 4));
        wordList.add(new Hotword("A Family in Queli", 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("Custom vocabulary ID: " + vocabulary.getVocabularyId());
    }
}

class Hotword {
    String text;
    int weight;

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

List custom vocabularies

HELPCODEESCAPE-java
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 {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio 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 {
        // The following is the URL for the Singapore region. If you are using a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary[] vocabularies = service.listVocabulary("testpfx");
        Gson gson = new GsonBuilder()
                .setPrettyPrinting()
                .create();
        System.out.println("Custom vocabularies: " + gson.toJson(vocabularies));
    }
}

Query a custom vocabulary

HELPCODEESCAPE-java
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 {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio 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 {
        // The following is the URL for the Singapore region. If you are using a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        // Replace with the actual custom vocabulary ID when querying
        Vocabulary vocabulary = service.queryVocabulary("vocab-testpfx-xxxx");
        Gson gson = new GsonBuilder()
                .setPrettyPrinting()
                .create();
        System.out.println("Custom vocabulary: " + gson.toJson(vocabulary.getData()));
    }
}

Update a custom vocabulary

HELPCODEESCAPE-java
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 {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio 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 {
        // The following is the URL for the Singapore region. If you are using a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

        JsonArray vocabularyJson = new JsonArray();
        List&lt;Hotword&gt; wordList = new ArrayList<>();
        wordList.add(new Hotword("Wu yi gong", 4, "en"));
        wordList.add(new Hotword("A Family in Queli", 4, "en"));

        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);
        // Replace with the actual custom vocabulary 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

HELPCODEESCAPE-java
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 {
    // 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: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // The following URL is for the Singapore region. To use the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        // Replace with the actual vocabulary ID when deleting
        service.deleteVocabulary("vocab-testpfx-xxxx");
    }
}

Custom hotwords Java SDK reference ​

Endpoint ​

International ​

Chinese mainland ​

VocabularyService ​

Constructor ​

createVocabulary() - Create a custom vocabulary ​

listVocabulary() - List custom vocabularies ​

queryVocabulary() - Query a custom vocabulary ​

updateVocabulary() - Update a custom vocabulary ​

deleteVocabulary() - Delete a custom vocabulary ​

Vocabulary class ​

Methods ​

Hotword object structure ​

Sample code ​

Create a custom vocabulary ​

List custom vocabularies ​

Query a custom vocabulary ​

Update a custom vocabulary ​

Delete a custom vocabulary ​

Custom hotwords Java SDK reference

Endpoint

International

Chinese mainland

VocabularyService

Constructor

createVocabulary() - Create a custom vocabulary

listVocabulary() - List custom vocabularies

queryVocabulary() - Query a custom vocabulary

updateVocabulary() - Update a custom vocabulary

deleteVocabulary() - Delete a custom vocabulary

Vocabulary class

Methods

Hotword object structure

Sample code

Create a custom vocabulary

List custom vocabularies

Query a custom vocabulary

Update a custom vocabulary

Delete a custom vocabulary