Custom hotwords Java 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 com.alibaba.dashscope.utils.Constants;

Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

VocabularyService class

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

Constructor

public VocabularyService(String apiKey)

Parameter	Type	Required	Description
apiKey	String	Yes	Your DashScope API key.

createVocabulary()

Create a custom vocabulary.

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

Parameter	Type	Required	Description
targetModel	String	Yes	The speech recognition model that uses this vocabulary. 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, max 10 characters.
vocabulary	JsonArray	Yes	The vocabulary entries. See Hotword object structure.

Returns: Vocabulary — use getVocabularyId() to retrieve the created vocabulary ID.

Show Example

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 {
  public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

  public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
    Constants.baseHttpApiUrl = "https://dashscope-intl.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;
  }
}

listVocabulary()

List custom vocabularies filtered by prefix.

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

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

Parameter	Type	Required	Description
prefix	String	Yes	Filter by vocabulary prefix.
pageIndex	int	No	Page number, starting from 0. Default: 0.
pageSize	int	No	Number of entries per page. Default: 10.

Returns: Vocabulary[] — each element has the following methods:

Method	Return type	Description
getVocabularyId()	String	The vocabulary ID.
getGmtCreate()	String	The creation time.
getGmtModified()	String	The last modification time.
getStatus()	String	`OK`: Ready. `UNDEPLOYED`: Not available.

Show Example

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 {
  public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

  public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
    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));
  }
}

queryVocabulary()

Query details of a specific custom vocabulary.

public Vocabulary queryVocabulary(String vocabularyId)
    throws NoApiKeyException, InputRequiredException

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

Returns: Vocabulary — has the following methods:

Method	Return type	Description
getVocabularyId()	String	The vocabulary ID.
getTargetModel()	String	The speech recognition model.
getVocabulary()	JsonArray	The vocabulary entries.
getStatus()	String	`OK`: Ready. `UNDEPLOYED`: Not available.
getGmtCreate()	String	The creation time.
getGmtModified()	String	The last modification time.
getData()	JsonObject	The complete data in JSON format.

Show Example

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 {
  public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

  public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

    VocabularyService service = new VocabularyService(apiKey);
    Vocabulary vocabulary = service.queryVocabulary("vocab-testpfx-xxxx");
    Gson gson = new GsonBuilder()
        .setPrettyPrinting()
        .create();
    System.out.println("Custom vocabulary: " + gson.toJson(vocabulary.getData()));
  }
}

updateVocabulary()

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

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

Parameter	Type	Required	Description
vocabularyId	String	Yes	The ID of the vocabulary to update.
vocabulary	JsonArray	Yes	The new vocabulary entries. See Hotword object structure.

Returns: void

Show Example

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 {
  public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

  public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
    Constants.baseHttpApiUrl = "https://dashscope-intl.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);
    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;
  }
}

deleteVocabulary()

Delete a custom vocabulary.

public void deleteVocabulary(String vocabularyId)
    throws NoApiKeyException, InputRequiredException

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

Returns: void

Show Example

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 {
  public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

  public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

    VocabularyService service = new VocabularyService(apiKey);
    service.deleteVocabulary("vocab-testpfx-xxxx");
  }
}

Hotword object structure

Each entry in the vocabulary JsonArray has the following fields:

Field	Type	Required	Description
text	String	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	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. Valid values vary by model. Fun-ASR: `zh` (Chinese), `en` (English), `ja` (Japanese).

​Prerequisites

​Service URL

​VocabularyService class

​Constructor

​createVocabulary()

​listVocabulary()

​queryVocabulary()

​updateVocabulary()

​deleteVocabulary()

​Hotword object structure

Prerequisites

Service URL

VocabularyService class

Constructor

createVocabulary()

listVocabulary()

queryVocabulary()

updateVocabulary()

deleteVocabulary()

Hotword object structure