热词是指用户可以预先定义的一组特定词汇或短语,这些词汇或短语在识别、翻译过程中会被赋予更高的优先级。使用热词可以显著提高这些特定词汇的识别、翻译准确率。针对您的特定业务领域,如果有部分词汇的语音识别、翻译效果不够好,可以将这些关键词或短语添加为热词进行优先识别或翻译,从而提升识别、翻译效果。
热词简介
热词通过热词列表的形式在SDK或API中使用,热词列表是JSON列表,其中每一个热词包含如下字段:
| 字段 | 类型 | 是否必填 | 说明 | 
| text | string | 是 | 热词文本。 热词用于提升识别/翻译的准确率,因此请使用实际词语而非任意字符组合。热词文本长度限制规则如下: 
 | 
| lang | string | 否 | 待识别语音的语言代码,支持对ASR模型对应的语种做热词加强。具体语种和语言代码对应关系请参见API详情。请在调用语音识别服务时保证该字段和源语言字段(Java: | 
| target_lang | string | 否 | 翻译目标语言。具体语种和语言代码对应关系请参见API详情。请在调用语音翻译服务时保证该字段和语音翻译时的翻译目标语言(Java: 如果需要输出多路翻译,需要逐个指定热词翻译目标语种,例如,将中文翻译成英文和日语的热词示例如下:  | 
| translation | string | 否 | 热词翻译目标。 例如希望将“夏洛特烦恼”翻译成“Goodbye Mr. Lose”:  | 
应用场景示例
为了提高电影名称的识别和翻译的准确率,将如下电影名称作为热词添加到项目中。
[
    {
        "text": "赛德克巴莱",
        "lang": "zh",
        "target_lang": "en",
        "translation": "Seediq Bale"
    },
    {
        "text": "夏洛特烦恼",
        "lang": "zh",
        "target_lang": "en",
        "translation": "Goodbye Mr. Lose"
    },
    {
        "text": "夏洛特烦恼",
        "lang": "zh",
        "target_lang": "ja",
        "translation": "夏洛の特別な悩み"
    }
]支持的模型列表
- gummy-realtime-v1 
- gummy-chat-v1 
计费说明
热词暂不收费。
前提条件
- 已开通服务并获得API-KEY:获取API Key。 
- 我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄漏风险,详情可参考配置API Key到环境变量。您也可以在代码中配置API-KEY,但是泄漏风险会提高。 
- 已安装最新版SDK:安装SDK。 
注意:
1、每个热词列表最多添加500个词,
2、每个账号默认分配10个热词列表额度,该额度由Paraformer和Gummy共享,如果有需要创建更多请联系我们。
API详情
使用不同API时,请确保使用同一账号进行操作。
创建热词表
Python SDK
通过VocabularyService类的create_vocabulary方法创建热词表。VocabularyService类的引入方式:from dashscope.audio.asr import *。
create_vocabulary方法返回热词表ID。
热词表字典各字段含义请参见热词简介。
def create_vocabulary(self, target_model: str, prefix: str, vocabulary: List[dict]) -> str:
    '''
    创建热词表
    param: target_model 热词表对应的语音识别模型版本
    param: prefix 热词表自定义前缀,仅允许数字和小写字母,小于十个字符。
    param: vocabulary 热词表字典
    return: 热词表标识符 vocabulary_id
    '''Java SDK
通过VocabularyService类的createVocabulary方法创建热词表。VocabularyService类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;。
createVocabulary方法返回热词表ID。
热词表字典各字段含义请参见热词简介。
/**
 * 创建新热词
 *
 * @param targetModel 热词对应的语音识别模型版本
 * @param prefix 热词自定义前缀,仅允许数字和小写字母,小于十个字符。
 * @param vocabulary 热词表
 * @return 热词表对象
 * @throws NoApiKeyException 如果apikey为空
 * @throws InputRequiredException 如果必须参数为空
 */
public Vocabulary createVocabulary(String targetModel, String prefix, JsonArray vocabulary)
    throws NoApiKeyException, InputRequiredException RESTful API
基本信息
| URL |  | 
| 请求方法 | POST | 
| 请求头 |  | 
| 消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:  | 
请求参数
| 参数 | 类型 | 默认值 | 是否必须 | 说明 | 
| model | string | - | 是 | 固定为 | 
| action | string | - | 是 | 固定为 | 
| target_model | string | - | 是 | 热词表对应的语音识别模型,为 | 
| prefix | string | - | 是 | 热词表自定义前缀,仅允许数字和小写字母,小于十个字符。 | 
| vocabulary | object[] | - | 是 | 热词表字典。各字段含义参见热词简介。 | 
响应参数
| 参数 | 类型 | 说明 | 
| vocabulary_id | string | 热词表ID。 | 
查询所有热词表
Python SDK
通过VocabularyService类的list_vocabularies方法查询所有热词表。VocabularyService类的引入方式:from dashscope.audio.asr import *。
def list_vocabularies(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
    '''
    查询已创建的所有热词表
    param: prefix 自定义前缀,如果设定则只返回指定前缀的热词表标识符列表。
    param: page_index 查询的页索引
    param: page_size 查询页大小
    return: 热词表标识符列表
    '''响应示例:
[
  {
    "gmt_create": "2025-04-22 14:23:35",
    "vocabulary_id": "yourVocabularyId",
    "gmt_modified": "2025-04-22 14:23:35",
    "status": "OK"
  }
]响应参数:
| 参数 | 类型 | 说明 | 
| vocabulary_id | string | 热词表ID。 | 
| gmt_create | string | 创建热词表的时间。 | 
| gmt_modified | string | 修改热词表的时间。 | 
| status | string | 状态: 
 | 
Java SDK
通过VocabularyService类的listVocabulary方法查询所有热词表。VocabularyService类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;。
/**
 * 查询已创建的所有热词表。默认的页索引为0,默认的页大小为10
 *
 * @param prefix 热词自定义前缀
 * @return 热词表对象数组
 * @throws NoApiKeyException 如果apikey为空
 * @throws InputRequiredException 如果必须参数为空
 */
public Vocabulary[] listVocabulary(String prefix)
    throws NoApiKeyException, InputRequiredException
/**
 * 查询已创建的所有热词表
 *
 * @param prefix 热词自定义前缀
 * @param pageIndex 查询的页索引
 * @param pageSize 查询的页大小
 * @return 热词表对象数组
 * @throws NoApiKeyException 如果apikey为空
 * @throws InputRequiredException 如果必须参数为空
 */
public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize)
    throws NoApiKeyException, InputRequiredException响应示例:
[
  {
    "gmt_create": "2025-04-22 14:23:35",
    "vocabulary_id": "yourVocabularyId",
    "gmt_modified": "2025-04-22 14:23:35",
    "status": "OK"
  }
]响应参数:
| 参数 | 类型 | 说明 | 
| vocabulary_id | string | 热词表ID。 | 
| gmt_create | string | 创建热词表的时间。 | 
| gmt_modified | string | 修改热词表的时间。 | 
| status | string | 状态: 
 | 
RESTful API
基本信息
| URL |  | 
| 请求方法 | POST | 
| 请求头 |  | 
| 消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:  | 
请求参数
| 参数 | 类型 | 默认值 | 是否必须 | 说明 | 
| model | string | - | 是 | 固定为 | 
| action | string | - | 是 | 固定为 | 
| prefix | string | - | 是 | 热词表自定义前缀,仅允许数字和小写字母,小于十个字符。 | 
| page_index | integer | 0 | 否 | 页码索引,从0开始计数。 | 
| page_size | integer | 10 | 否 | 每页包含数据条数。 | 
响应参数
| 参数 | 类型 | 说明 | 
| vocabulary_id | string | 热词表ID。 | 
| gmt_create | string | 创建热词表的时间。 | 
| gmt_modified | string | 修改热词表的时间。 | 
| status | string | 状态: 
 | 
查询指定热词表
Python SDK
通过VocabularyService类的query_vocabulary方法查询指定热词表。VocabularyService类的引入方式:from dashscope.audio.asr import *。
def query_vocabulary(self, vocabulary_id: str) -> List[dict]:
    '''
    获取热词表内容
    param: vocabulary_id 热词表标识符
    return: 热词表
    '''响应示例:
{
    "gmt_create": "2025-04-22 14:23:35",
    "vocabulary": [
      {
        "target_lang": "en",
        "translation": "Goodbye Mr. Lose",
        "text": "夏洛特烦恼",
        "lang": "zh"
      }
    ],
    "target_model": "gummy-realtime-v1",
    "gmt_modified": "2025-04-22 14:23:35",
    "status": "OK"
  }响应参数:
| 参数 | 类型 | 说明 | 
| vocabulary | object[] | 热词表字典。各字段含义参见热词简介。 | 
| gmt_create | string | 创建热词表的时间。 | 
| gmt_modified | string | 修改热词表的时间。 | 
| target_model | string | 热词表对应的语音识别模型,为 | 
| status | string | 状态: 
 | 
Java SDK
通过VocabularyService类的queryVocabulary方法查询指定热词表。VocabularyService类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;。
/**
 * 查询指定热词表
 *
 * @param vocabularyId 需要查询的热词表
 * @return 热词表对象
 * @throws NoApiKeyException 如果apikey为空
 * @throws InputRequiredException 如果必须参数为空
 */
public Vocabulary queryVocabulary(String vocabularyId)
    throws NoApiKeyException, InputRequiredException响应示例:
{
    "gmt_create": "2025-04-22 14:23:35",
    "vocabulary": [
      {
        "target_lang": "en",
        "translation": "Goodbye Mr. Lose",
        "text": "夏洛特烦恼",
        "lang": "zh"
      }
    ],
    "target_model": "gummy-realtime-v1",
    "gmt_modified": "2025-04-22 14:23:35",
    "status": "OK"
  }响应参数:
| 参数 | 类型 | 说明 | 
| vocabulary | object[] | 热词表字典。各字段含义参见热词简介。 | 
| gmt_create | string | 创建热词表的时间。 | 
| gmt_modified | string | 修改热词表的时间。 | 
| target_model | string | 热词表对应的语音识别模型,为 | 
| status | string | 状态: 
 | 
RESTful API
基本信息
| URL |  | 
| 请求方法 | POST | 
| 请求头 |  | 
| 消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:  | 
请求参数
| 参数 | 类型 | 默认值 | 是否必须 | 说明 | 
| model | string | - | 是 | 固定为 | 
| action | string | - | 是 | 固定为 | 
| vocabulary_id | string | - | 是 | 待查询热词表ID。 | 
响应参数
| 参数 | 类型 | 说明 | 
| vocabulary | object[] | 热词表字典。各字段含义参见热词简介。 | 
| gmt_create | string | 创建热词表的时间。 | 
| gmt_modified | string | 修改热词表的时间。 | 
| target_model | string | 热词表对应的语音识别模型,为 | 
| status | string | 状态: 
 | 
更新热词表
Python SDK
通过VocabularyService类的update_vocabulary方法更新热词表。VocabularyService类的引入方式:from dashscope.audio.asr import *。
def update_vocabulary(self, vocabulary_id: str, vocabulary: List[dict]) -> None:
    '''
    用新的热词表替换已有热词表
    param: vocabulary_id 需要替换的热词表标识符
    param: vocabulary 热词表
    '''Java SDK
通过VocabularyService类的updateVocabulary方法更新热词表。VocabularyService类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;。
/**
 * 更新热词表
 *
 * @param vocabularyId 需要更新的热词表
 * @param vocabulary 热词表对象
 * @throws NoApiKeyException 如果apikey为空
 * @throws InputRequiredException 如果必须参数为空
 */
public void updateVocabulary(String vocabularyId, JsonArray vocabulary)
    throws NoApiKeyException, InputRequiredExceptionRESTful API
基本信息
| URL |  | 
| 请求方法 | POST | 
| 请求头 |  | 
| 消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:  | 
请求参数
| 参数 | 类型 | 默认值 | 是否必须 | 说明 | 
| model | string | - | 是 | 固定为 | 
| action | string | - | 是 | 固定为 | 
| vocabulary_id | string | - | 是 | 待更新热词表ID。 | 
| vocabulary | object[] | - | 是 | 更新后的热词表字典。各字段含义参见热词简介。 | 
响应参数
删除热词表
Python SDK
通过VocabularyService类的delete_vocabulary方法删除热词表。VocabularyService类的引入方式:from dashscope.audio.asr import *。
def delete_vocabulary(self, vocabulary_id: str) -> None:
    '''
    删除热词表
    param: vocabulary_id 需要删除的热词表标识符
    '''Java SDK
通过VocabularyService类的deleteVocabulary方法删除热词表。VocabularyService类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;。
/**
 * 删除热词表
 *
 * @param vocabularyId 需要删除的热词表
 * @throws NoApiKeyException 如果apikey为空
 * @throws InputRequiredException 如果必须参数为空
 */
public void deleteVocabulary(String vocabularyId)
    throws NoApiKeyException, InputRequiredExceptionRESTful API
基本信息
| URL |  | 
| 请求方法 | POST | 
| 请求头 |  | 
| 消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:  | 
请求参数
| 参数 | 类型 | 默认值 | 是否必须 | 说明 | 
| model | string | - | 是 | 固定为 | 
| action | string | - | 是 | 固定为 | 
| vocabulary_id | string | - | 是 | 待删除热词表ID。 | 
响应参数
使用创建的热词表进行语音识别/翻译
本文档介绍热词管理接口的功能,支持对热词进行创建、查询、更新和删除操作。若需在语音识别/翻译中调用已创建的热词表,请按以下步骤操作(请确保热词表与语音识别/翻译使用同一账号):
- 获取热词表ID - 调用创建热词表或查询所有热词表接口,获取热词表ID(根据编程语言选择合适的接口。对于Java和Python以外的其他编程语言,如 Go、C#、PHP、Node.js 等,请使用RESTful接口)。 
- 调用Gummy语音识别/翻译API - 请根据您所使用的编程语言选择对应API文档,将第1步中获取的热词表ID作为 - vocabulary_id/- vocabularyId参数传递至语音识别接口(调用接口时,可通过请求参数对音频采样率、音频格式等进行调节):- 实时语音识别/翻译- Java:Java SDK 
- Python:Python SDK 
- 其他编程语言(如Go、C#、PHP、Node.js等):WebSocket API 
 - 一句话识别/翻译- Java:Java SDK 
- Python:Python SDK 
- 其他编程语言(如Go、C#、PHP、Node.js等):WebSocket API 
 
以下示例代码展示如何创建一个热词表,并调用gummy-realtime-v1模型识别本地音频文件。
示例代码仅提供 Java 和 Python 的基础示例,实际业务场景中的相关代码需您根据具体需求自行开发。示例中用到的音频为:asr_example.wav。
import dashscope
from dashscope.audio.asr import *
# 若没有将API Key配置到环境变量中,需将your-api-key替换为自己的API Key
# dashscope.api_key = "your-api-key"
prefix = 'prefix'
target_model = "gummy-realtime-v1"
my_vocabulary = [
    {"text": "阿里巴巴语音实验室", "lang": "zh", "target_lang": "en", "translation": "Alibaba Speech Lab"}
]
# 创建热词
service = VocabularyService()
vocabulary_id = service.create_vocabulary(
    prefix=prefix,
    target_model=target_model,
    vocabulary=my_vocabulary)
print(f"热词表ID为:{vocabulary_id}")
# 使用热词进行语音识别
translator = TranslationRecognizerRealtime(
    model=target_model,  # 设置模型
    format="wav",  # 设置音频格式
    sample_rate=16000,  # 设置采样率
    translation_target_languages=["en"],  # 设置翻译目标语言
    translation_enabled=True,  # 启用翻译
    vocabulary_id=vocabulary_id,  # 传入热词表ID
    callback=None,
)
result = translator.call("asr_example.wav")
if not result.error_message:
    print("Request ID:", result.request_id)
    print("识别结果:")
    for transcription_result in result.transcription_result_list:
        print(transcription_result.text)
    print("翻译结果:")
    for translation_result in result.translation_result_list:
        print(translation_result.get_translation('en').text)
else:
    print("出现异常:", result.error_message)import com.alibaba.dashscope.audio.asr.translation.TranslationRecognizerParam;
import com.alibaba.dashscope.audio.asr.translation.TranslationRecognizerRealtime;
import com.alibaba.dashscope.audio.asr.translation.results.TranscriptionResult;
import com.alibaba.dashscope.audio.asr.translation.results.TranslationRecognizerResultPack;
import com.alibaba.dashscope.audio.asr.translation.results.TranslationResult;
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.google.gson.JsonArray;
import com.google.gson.JsonObject;
import java.io.File;
import java.util.ArrayList;
import java.util.List;
public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY"); // 若没有将API Key配置到环境变量中,需将apiKey替换为自己的API Key
    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        String targetModel = "gummy-realtime-v1";
        // 定义热词类
        class HotWord {
            String text;
            String lang;
            String targetLang;
            String translation;
            public HotWord(String text, String lang, String targetLang, String translation) {
                this.text = text;
                this.lang = lang;
                this.targetLang = targetLang;
                this.translation = translation;
            }
        }
        JsonArray vocabulary = new JsonArray();
        List<HotWord> wordList = new ArrayList<>();
        wordList.add(new HotWord("阿里巴巴语音实验室", "zh", "en", "Alibaba Speech Lab"));
        for (HotWord word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("lang", word.lang);
            jsonObject.addProperty("target_lang", word.targetLang);
            jsonObject.addProperty("translation", word.translation);
            vocabulary.add(jsonObject);
        }
        // 创建热词
        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary myVoc = service.createVocabulary(targetModel, "prefix", vocabulary);
        System.out.println("热词表ID:" + myVoc.getVocabularyId());
        // 使用热词进行语音识别
        String targetLanguage = "en";
        // 创建TranslationRecognizerRealtime实例
        TranslationRecognizerRealtime translator = new TranslationRecognizerRealtime();
        // 设置请求参数
        TranslationRecognizerParam param =
                TranslationRecognizerParam.builder()
                        .apiKey(apiKey)
                        .model("gummy-realtime-v1") // 设置模型
                        .format("wav") // 设置音频格式
                        .sampleRate(16000) // 设置采样率
                        .transcriptionEnabled(true) // 启用语音识别
                        .translationEnabled(true) // 启用翻译
                        .translationLanguages(new String[] {targetLanguage}) // 设置翻译目标语言
                        .vocabularyId(myVoc.getVocabularyId()) // 设置热词表ID
                        .build();
        // 解析识别/翻译结果
        TranslationRecognizerResultPack result = translator.call(param, new File("asr_example.wav"));
        if (result.getError() != null) {
            System.out.println("error: " + result.getError());
            throw new RuntimeException(result.getError());
        } else {
            System.out.println("RequestId:" + result.getRequestId());
            System.out.println("识别结果:");
            ArrayList<TranscriptionResult> transcriptionResults = result.getTranscriptionResultList();
            for (int i = 0; i < transcriptionResults.size(); i++) {
                System.out.println(transcriptionResults.get(i).getText());
            }
            System.out.println("翻译结果:");
            ArrayList<TranslationResult> translationResultList = result.getTranslationResultList();
            for (int i = 0; i < translationResultList.size(); i++) {
                System.out.println(translationResultList.get(i).getTranslation(targetLanguage).getText());
            }
        }
        System.exit(0);
    }
}错误码说明
如遇报错问题,请参见错误信息进行排查。