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

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

To use the Singapore region, set Constants.baseHttpApiUrl before initialization:

import com.alibaba.dashscope.utils.Constants;

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

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

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

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:

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:

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:

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

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://help.aliyun.com/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 URL is for the China (Beijing) region. The URLs vary by region.
        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("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

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://help.aliyun.com/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 URL is for the China (Beijing) region. The URLs vary by region.
        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("Custom vocabularies: " + 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 {
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://help.aliyun.com/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 URL is for the China (Beijing) region. The URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.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

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://help.aliyun.com/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 URL is for the China (Beijing) region. The URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> 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

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://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: 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 China (Beijing) region. The URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

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