Custom hotwords - Qwen Cloud

Hotwords help the model recognize terms it might otherwise miss -- business terms, product names, or proper nouns.

Hotwords overview

Submit a JSON array of hotword objects. Example: Improve movie title recognition (Fun-ASR and Paraformer series models)

[
  {"text": "赛德克巴莱", "weight": 4, "lang": "zh"},
  {"text": "Seediq Bale", "weight": 4, "lang": "en"},
  {"text": "夏洛特烦恼", "weight": 4, "lang": "zh"},
  {"text": "Goodbye Mr. Loser", "weight": 4, "lang": "en"},
  {"text": "阙里人家", "weight": 4, "lang": "zh"},
  {"text": "Confucius' Family", "weight": 4, "lang": "en"}
]

Field descriptions:

Field	Type	Required	Description
text	string	Yes	The hotword text. Must be supported by the selected model. Use actual words, not random characters. See length rules below.
weight	int	Yes	Priority weight, an integer from 1 to 5. Start with 4. Increase if results are weak, but too high a weight can hurt recognition of other words.
lang	string	No	Language code. Boosts hotwords for a specific language. Leave empty for auto-detection. See the model's API reference for supported codes. If you set `language_hints`, only matching hotwords take effect.

Hotword text length rules:

Contains non-ASCII characters: Maximum 15 characters total, including non-ASCII characters (Chinese, Japanese kana, Korean Hangul, Russian Cyrillic) and ASCII characters. Examples:
- "厄洛替尼盐酸盐" (7 Chinese characters)
- "EGFR抑制剂" (3 Chinese characters and 4 ASCII characters, for a total of 7 characters)
- "こんにちは" (5 characters)
- "Фенибут Белфарм" (15 characters, including the space)
- "Клофелин Белмедпрепараты" (24 characters) -- exceeds limit
Contains only ASCII characters: Maximum 7 segments. A segment is a sequence of characters separated by spaces. Examples:
- "Exothermic reaction" -- 2 segments
- "Human immunodeficiency virus type 1" -- 5 segments
- "The effect of temperature variations on enzyme activity in biochemical reactions" -- 11 segments, exceeds limit

Supported models

Hotwords are supported by Fun-ASR models. The following models are available in the international region:

Real-time speech recognition: fun-asr-realtime, fun-asr-realtime-2025-11-07
Non-real-time speech recognition: fun-asr, fun-asr-2025-11-07, fun-asr-2025-08-25, fun-asr-mtl, fun-asr-mtl-2025-08-25

For the full model list, see Speech-to-text models.

Billing

Hotwords are free.

Hotword quantity limits

Each account can create up to 10 hotword lists, shared across all models. To increase this limit, submit a request.
Each hotword list can have up to 500 words.

Getting started

Workflow

Create a hotword list by calling the Create API. Set target_model (or targetModel in Java) to the speech recognition model you plan to use. If you already have a list, skip this step and call Query all to view it.
Pass the hotword list ID to the speech recognition API. The model must match the target_model (or targetModel in Java) from step 1.

Prerequisites

Get an API key: Get your API key and export it as an environment variable.
Install the SDK: Install the DashScope SDK.

Code examples

Audio file used in the examples: asr_example.wav.

Python
Java

import dashscope
from dashscope.audio.asr import *
import os

# If you have not configured an environment variable, replace the following line with your API key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
dashscope.base_websocket_api_url = 'wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'
prefix = 'testpfx'
target_model = "fun-asr-realtime"

my_vocabulary = [
  {"text": "Speech Laboratory", "weight": 4}
]

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

try:
  if service.query_vocabulary(vocabulary_id)['status'] == 'OK':
    recognition = Recognition(model=target_model,
                            format='wav',
                            sample_rate=16000,
                            callback=None,
                            vocabulary_id=vocabulary_id)
    result = recognition.call('asr_example.wav')
    print(result.output)
finally:
  service.delete_vocabulary(vocabulary_id)

import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
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.io.File;
import java.util.ArrayList;
import java.util.List;

public class Main {
  // If you have not configured an environment variable, replace the following line with your 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 {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    Constants.baseWebsocketApiUrl = "wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference";

    String targetModel = "fun-asr-realtime";

    JsonArray vocabularyJson = new JsonArray();
    List<Hotword> wordList = new ArrayList<>();
    wordList.add(new Hotword("Speech Laboratory", 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);

    try {
      if ("OK".equals(service.queryVocabulary(vocabulary.getVocabularyId()).getStatus())) {
        Recognition recognizer = new Recognition();
        RecognitionParam param =
            RecognitionParam.builder()
                .model(targetModel)
                .apiKey(apiKey)
                .format("wav")
                .sampleRate(16000)
                .vocabularyId(vocabulary.getVocabularyId())
                .build();

        try {
          System.out.println("Recognition result: " + recognizer.call(param, new File("asr_example.wav")));
        } catch (Exception e) {
          e.printStackTrace();
        } finally {
          recognizer.getDuplexApi().close(1000, "bye");
        }
      }
    } finally {
      service.deleteVocabulary(vocabulary.getVocabularyId());
    }
    System.exit(0);
  }
}

class Hotword {
  String text;
  int weight;

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

Advanced usage

Adjust hotword weights

Weight controls how strongly the model favors a hotword. Set it appropriately to improve target word accuracy without introducing false recognitions.

Weight	Effect	Best for
1-2	Slight preference	Hotwords that sound similar to common words, where overcorrection must be avoided
3-4	Clear preference (recommended)	The best starting point for most scenarios
5	Forced preference	Use only when the term appears frequently and is unlikely to be confused with other words. An excessively high weight can cause phonetically similar words to be misrecognized as the hotword.

Start with weight=4 and adjust incrementally based on recognition results.

Design hotword lists

Group by scenario: Create separate vocabulary lists for different business scenarios (for example, one for medical terms and another for product names) to simplify maintenance and reuse.
Mix multiple languages: A single vocabulary list can contain terms in different languages. Use the lang field to distinguish them. When language_hints is specified during speech recognition, only hotwords that match the specified language take effect.
Clean up regularly: Delete unused vocabulary lists to free up quota. Each account supports up to 10 lists.

API reference

Use the same account for all operations.

Create a hotword list

For the hotword list JSON format, see Hotwords overview.

Python SDK
Java SDK
RESTful API

API description

target_model must match the model used in your speech recognition calls.

def create_vocabulary(self, target_model: str, prefix: str, vocabulary: List[dict]) -> str:
  '''
  Create a hotword list.
  param: target_model The speech recognition model (must match your recognition calls).
  param: prefix Custom prefix (<10 lowercase letters/digits).
  param: vocabulary The hotword list.
  return: The hotword list ID.
  '''

Code example

import dashscope
from dashscope.audio.asr import *
import os

# If you have not configured an environment variable, replace the following line with your API key: dashscope.api_key = "sk-xxx"
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}
]

# Create a hotword
service = VocabularyService()
vocabulary_id = service.create_vocabulary(
  prefix=prefix,
  target_model=target_model,
  vocabulary=my_vocabulary)

print(f"The hotword list ID is: {vocabulary_id}")

API description

targetModel must match the model used in your speech recognition calls.

/**
 * Create a hotword list.
 *
 * @param targetModel The speech recognition model (must match your recognition calls).
 * @param prefix Custom prefix (<10 lowercase letters/digits).
 * @param vocabulary The hotword list.
 * @return The hotword list object.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public Vocabulary createVocabulary(String targetModel, String prefix, JsonArray vocabulary)
  throws NoApiKeyException, InputRequiredException

Code 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 {
  // If you have not configured an environment variable, replace the following line with your 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 {
    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 Yigong", 4));
    wordList.add(new Hotword("Queli Renjia", 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("Hotword list ID: " + vocabulary.getVocabularyId());
  }
}

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

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

URL

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	`Bearer $DASHSCOPE_API_KEY`.
Content-Type	string	Yes	`application/json`.

Request body

target_model must match the model used in your speech recognition calls.

Parameter	Type	Default	Required	Description
model	string	-	Yes	Set to `speech-biasing`.
action	string	-	Yes	Set to `create_vocabulary`.
target_model	string	-	Yes	The speech recognition model for this hotword list. Must match the model in your recognition calls. See Supported models.
prefix	string	-	Yes	A name for the hotword list (<10 lowercase letters/digits). Appears in the hotword list ID. Example: prefix "testpfx" produces ID "vocab-testpfx-51773d05xxxxxx".
vocabulary	array[object]	-	Yes	The hotword list. See Hotwords overview.

Request body example

{
  "model": "speech-biasing",
  "input": {
    "action": "create_vocabulary",
    "target_model": "fun-asr",
    "prefix": "testpfx",
    "vocabulary": [
          {"text": "Seediq Bale", "weight": 4, "lang": "zh"}
    ]
  }
}

Response body

Parameter	Type	Description
vocabulary_id	string	The hotword list ID.

Response body example

{
  "output": {
    "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx"
  },
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

curl example

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "create_vocabulary",
    "target_model": "fun-asr",
    "prefix": "testpfx",
    "vocabulary": [
          {"text": "Seediq Bale", "weight": 4}
    ]
  }
}'

Query all hotword lists

Python SDK
Java SDK
RESTful API

API description

def list_vocabularies(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
  '''
  List all hotword lists.
  param: prefix Filter by prefix. Returns only matching lists.
  param: page_index Page index.
  param: page_size Page size.
  return: A list of hotword list identifiers.
  '''

Code example

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

# If you have not configured an environment variable, replace the following line with your API key: dashscope.api_key = "sk-xxx"
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"Hotword list: {json.dumps(vocabularies)}")

Response example

[
  {
  "gmt_create": "2025-04-22 14:23:35",
  "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx",
  "gmt_modified": "2025-04-22 14:23:35",
  "status": "OK"
  }
]

API description

/**
 * List all hotword lists. Defaults: page index 0, page size 10.
 *
 * @param prefix Filter by prefix.
 * @return An array of hotword list objects.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public Vocabulary[] listVocabulary(String prefix)
  throws NoApiKeyException, InputRequiredException

/**
 * List all hotword lists.
 *
 * @param prefix Filter by prefix.
 * @param pageIndex Page index.
 * @param pageSize Page size.
 * @return An array of hotword list objects.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize)
  throws NoApiKeyException, InputRequiredException

Code 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 {
  // If you have not configured an environment variable, replace the following line with your 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 {
    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("Hotword list: " + gson.toJson(vocabularies));
  }
}

Response example

[
  {
  "gmt_create": "2025-04-22 14:23:35",
  "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx",
  "gmt_modified": "2025-04-22 14:23:35",
  "status": "OK"
  }
]

URL

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	`Bearer $DASHSCOPE_API_KEY`.
Content-Type	string	Yes	`application/json`.

Request body

model: Set to speech-biasing.

Parameter	Type	Default	Required	Description
model	string	-	Yes	Set to `speech-biasing`.
action	string	-	Yes	Set to `list_vocabulary`.
prefix	string	-	No	Filter by prefix (<10 lowercase letters/digits).
page_index	integer	0	No	Page number, starting from 0.
page_size	integer	10	No	Entries per page.

Request body example

{
  "model": "speech-biasing",
  "input": {
    "action": "list_vocabulary",
    "prefix": "testpfx",
    "page_index": 0,
    "page_size": 10
  }
}

Response body

Parameter	Type	Description
vocabulary_id	string	The hotword list ID.
gmt_create	string	Creation time.
gmt_modified	string	Last modified time.
status	string	Status: `OK` (ready) or `UNDEPLOYED` (not ready).

Response body example

{
  "output": {
  "vocabulary_list": [
      {
    "gmt_create": "2025-12-19 11:47:11",
    "gmt_modified": "2025-12-19 11:47:11",
    "status": "OK",
    "vocabulary_id": "vocab-testpfx-xxxxxxxx"
      }
  ]
  },
  "usage": {
  "count": 1
  },
  "request_id": "10e8cde2-b711-4609-b19b-xxxxxx"
}

curl example

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "list_vocabulary",
    "prefix": "testpfx",
    "page_index": 0,
    "page_size": 10
  }
}'

Query a specific hotword list

Python SDK
Java SDK
RESTful API

API description

def query_vocabulary(self, vocabulary_id: str) -> List[dict]:
  '''
  Get a hotword list by ID.
  param: vocabulary_id The hotword list ID.
  return: The hotword list.
  '''

Code example

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

# If you have not configured an environment variable, replace the following line with your API key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

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

service = VocabularyService()
# Replace with your actual hotword list ID when querying.
vocabulary = service.query_vocabulary("vocab-testpfx-xxx")
print(f"Hotword list: {json.dumps(vocabulary, ensure_ascii=False)}")

Response example

{
  "gmt_create": "2025-12-19 11:47:11",
  "gmt_modified": "2025-12-19 11:47:11",
  "status": "OK",
  "target_model": "fun-asr",
  "vocabulary": [
  {
      "lang": "zh",
      "text": "Seediq Bale",
      "weight": 4
  }
  ]
}

API description

/**
 * Query a specific hotword list.
 *
 * @param vocabularyId The hotword list ID.
 * @return The hotword list object.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public Vocabulary queryVocabulary(String vocabularyId)
  throws NoApiKeyException, InputRequiredException

Code 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 {
  // If you have not configured an environment variable, replace the following line with your 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 {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

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

Response example

{
  "gmt_create": "2025-12-19 11:47:11",
  "gmt_modified": "2025-12-19 11:47:11",
  "status": "OK",
  "target_model": "fun-asr",
  "vocabulary": [
  {
      "lang": "zh",
      "text": "Seediq Bale",
      "weight": 4
  }
  ]
}

URL

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	`Bearer $DASHSCOPE_API_KEY`.
Content-Type	string	Yes	`application/json`.

Request body

model: Set to speech-biasing.

Parameter	Type	Default	Required	Description
model	string	-	Yes	Set to `speech-biasing`.
action	string	-	Yes	Set to `query_vocabulary`.
vocabulary_id	string	-	Yes	The hotword list ID to query.

Request body example

{
  "model": "speech-biasing",
  "input": {
    "action": "query_vocabulary",
    "vocabulary_id": "vocab-testpfx-xxxx"
  }
}

Response body

Parameter	Type	Description
vocabulary	object[]	The hotword list. See Hotwords overview.
gmt_create	string	Creation time.
gmt_modified	string	Last modified time.
target_model	string	The speech recognition model for this hotword list. See Supported models.
status	string	Status: `OK` (ready) or `UNDEPLOYED` (not ready).

Response body example

{
  "output": {
  "gmt_create": "2025-12-19 11:47:11",
  "gmt_modified": "2025-12-19 11:47:11",
  "status": "OK",
  "target_model": "fun-asr",
  "vocabulary": [
      {
    "lang": "zh",
    "text": "Seediq Bale",
    "weight": 4
      }
  ]
  },
  "usage": {
  "count": 1
  },
  "request_id": "3d461d3f-b2c4-4de5-xxxx"
}

curl example

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "query_vocabulary",
    "vocabulary_id": "vocab-testpfx-xxxx"
  }
}'

Update a hotword list

Python SDK
Java SDK
RESTful API

API description

def update_vocabulary(self, vocabulary_id: str, vocabulary: List[dict]) -> None:
  '''
  Replace a hotword list.
  param: vocabulary_id The hotword list ID to replace.
  param: vocabulary The new hotword list.
  '''

Code example

import dashscope
from dashscope.audio.asr import *
import os

# If you have not configured an environment variable, replace the following line with your API key: dashscope.api_key = "sk-xxx"
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": "zh"}
]
# Replace with your actual hotword list ID.
service.update_vocabulary("vocab-testpfx-xxx", my_vocabulary)

API description

/**
 * Update a hotword list.
 *
 * @param vocabularyId The hotword list ID to update.
 * @param vocabulary The new hotword list.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public void updateVocabulary(String vocabularyId, JsonArray vocabulary)
  throws NoApiKeyException, InputRequiredException

Code 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 {
  // If you have not configured an environment variable, replace the following line with your 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 {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

    JsonArray vocabularyJson = new JsonArray();
    List<Hotword> wordList = new ArrayList<>();
    wordList.add(new Hotword("Wu Yigong", 4, "zh"));
    wordList.add(new Hotword("Queli Renjia", 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);
    // Replace with your actual hotword list 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;
  }
}

URL

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	`Bearer $DASHSCOPE_API_KEY`.
Content-Type	string	Yes	`application/json`.

Request body

model: Set to speech-biasing.

Parameter	Type	Default	Required	Description
model	string	-	Yes	Set to `speech-biasing`.
action	string	-	Yes	Set to `update_vocabulary`.
vocabulary_id	string	-	Yes	The hotword list ID to update.
vocabulary	object[]	-	Yes	The new hotword list. See Hotwords overview.

Request body example

{
  "model": "speech-biasing",
  "input": {
    "action": "update_vocabulary",
    "vocabulary_id": "vocab-testpfx-6977ae49f65c4c3db054727cxxxxxxxx",
    "vocabulary": [
          {"text": "Seediq Bale", "weight": 4, "lang": "zh"}
    ]
  }
}

Response body example

{
  "output": {},
  "usage": {
  "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

curl example

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "update_vocabulary",
    "vocabulary_id": "vocab-testpfx-xxx",
    "vocabulary": [
          {"text": "Seediq Bale", "weight": 4, "lang": "zh"}
    ]
  }
}'

Delete a hotword list

Python SDK
Java SDK
RESTful API

API description

def delete_vocabulary(self, vocabulary_id: str) -> None:
  '''
  Delete a hotword list.
  param: vocabulary_id The hotword list ID to delete.
  '''

Code example

import dashscope
from dashscope.audio.asr import *
import os

# If you have not configured an environment variable, replace the following line with your API key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

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

service = VocabularyService()
# Replace with your actual hotword list ID.
service.delete_vocabulary("vocab-testpfx-xxxx")

API description

/**
 * Delete a hotword list.
 *
 * @param vocabularyId The hotword list ID to delete.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public void deleteVocabulary(String vocabularyId)
  throws NoApiKeyException, InputRequiredException

Code 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 {
  // If you have not configured an environment variable, replace the following line with your 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 {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

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

URL

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	`Bearer $DASHSCOPE_API_KEY`.
Content-Type	string	Yes	`application/json`.

Request body

model: Set to speech-biasing.

Parameter	Type	Default	Required	Description
model	string	-	Yes	Set to `speech-biasing`.
action	string	-	Yes	Set to `delete_vocabulary`.
vocabulary_id	string	-	Yes	The hotword list ID to delete.

Request body example

{
  "model": "speech-biasing",
  "input": {
    "action": "delete_vocabulary",
    "vocabulary_id": "vocab-testpfx-xxx"
  }
}

Response body example

{
  "output": {},
  "usage": {
  "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

curl example

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "speech-biasing",
  "input": {
    "action": "delete_vocabulary",
    "vocabulary_id": "vocab-testpfx-xxx"
  }
}'

FAQ

Why don't hotwords improve recognition accuracy?

Check the following in order:

Model mismatch: The target_model specified when creating the list must match the model used by the speech recognition API. A mismatch doesn't cause an error, and recognition still returns results, but the hotwords don't take effect.
Unsupported model: The model must belong to the Fun-ASR family. Other families don't support hotwords. Calling the API with an unsupported model doesn't return an error, but the results may lack hotword enhancement.
Inappropriate weight: Increase the weight from 4 to 5 and observe the results. If phonetically similar words start being misrecognized as the hotword, reduce it back to 4.
Hotword list status: Use the Query API to confirm that status is OK.

Are hotwords used differently in real-time and file-based recognition?

Hotword lists are created the same way. The calling method differs:

Real-time speech recognition: Pass vocabulary_id in the Recognition or WebSocket connection parameters.
File-based speech recognition: Pass vocabulary_id in the Transcription request parameters.

In both cases, target_model must match the speech recognition model used in the API call.

How to improve recognition accuracy beyond hotwords?

In addition to hotwords, consider the following:

Audio quality: Match the sample rate to the model requirements (16 kHz or 8 kHz) and reduce background noise.
Choose the right model: Different scenarios call for different models. For details, see Speech-to-text models.
Specify the language: Declare the audio language through language_hints to improve accuracy in single-language scenarios.

​Hotwords overview

​Supported models

​Billing

​Hotword quantity limits

​Getting started

​Workflow

​Prerequisites

​Code examples

​Advanced usage

​Adjust hotword weights

​Design hotword lists

​API reference

​Create a hotword list

​Query all hotword lists

​Query a specific hotword list

​Update a hotword list

​Delete a hotword list

​FAQ

​Why don't hotwords improve recognition accuracy?

​Are hotwords used differently in real-time and file-based recognition?

​How to improve recognition accuracy beyond hotwords?

Hotwords overview

Supported models

Billing

Hotword quantity limits

Getting started

Workflow

Prerequisites

Code examples

Advanced usage

Adjust hotword weights

Design hotword lists

API reference

Create a hotword list

Query all hotword lists

Query a specific hotword list

Update a hotword list

Delete a hotword list

FAQ

Why don't hotwords improve recognition accuracy?

Are hotwords used differently in real-time and file-based recognition?

How to improve recognition accuracy beyond hotwords?