跳转到主要内容
千问AI平台 home page
文档
定制热词

定制热词HTTP API参考

通过HTTP API管理定制热词列表，包括创建、查询、更新和删除热词列表。

用户指南：提升识别准确率。热词列表数量上限等使用限制详见热词限制与计费。

接口地址

POST https://maas.qianwenaiapi.com/api/v1/services/audio/asr/customization

请求头

参数类型是否必选说明
Authorizationstring是鉴权令牌，格式为Bearer $DASHSCOPE_API_KEY，使用时，将“$DASHSCOPE_API_KEY”替换为实际的API Key。
Content-Typestring是请求体的媒体类型，固定为application/json。

创建热词列表

请求体

curl -X POST https://maas.qianwenaiapi.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": "赛德克巴莱", "weight": 4}
        ]
    }
}'
参数类型说明
modelstring（必选） 定制热词模型，固定为speech-biasing。
inputobject（必选） 输入参数对象。
input.actionstring（必选） 操作类型，固定为create_vocabulary。
input.target_modelstring（必选） 使用热词列表的语音识别模型，必须与后续调用语音识别接口时使用的模型一致。
input.prefixstring（必选） 热词列表自定义前缀，仅允许数字和小写字母，长度不超过10个字符。
input.vocabularyarray[object]（必选） 热词列表数组。
input.vocabulary.textstring（必选） 热词文本。 热词文本的语言必须在所选模型的支持范围内，不同模型支持的语言各不相同。 热词用于提升识别的准确率，请使用实际词语而非任意字符组合。 长度限制：含非 ASCII 字符时不超过 15 个字符；纯 ASCII 时空格分隔片段不超过 7 个。
input.vocabulary.weightinteger（必选） 热词权重。常用值：4。 取值范围：[1, 5]。 如果效果不明显，可以适当增加权重，但权重过大可能产生负面效果，导致其他词语识别不准确。
input.vocabulary.langstring（可选） 待识别音频的语言代码。设置后，系统将对指定语种进行热词识别增强。如果无法提前确定语种，可不设置，模型会自动识别语种。 取值范围（因模型而异）：
  • Paraformer：
  • zh: 中文
  • en: 英文
  • ja: 日语
  • yue: 粤语
  • ko: 韩语
  • de：德语
  • fr：法语
  • ru：俄语
  • Fun-ASR：
  • zh: 中文
  • en: 英文
  • ja: 日语

返回体

{
    "output": {
        "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "aee47022-2352-40fe-acfa-xxxx"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据。
output.vocabulary_idstring创建的热词列表ID。
usageobject本次请求用量信息。
usage.countinteger创建的热词列表数量，固定为1。

批量查询热词列表

请求体

curl -X POST https://maas.qianwenaiapi.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
    }
}'
参数类型说明
modelstring（必选） 定制热词模型，固定为speech-biasing。
inputobject（必选） 输入参数对象。
input.actionstring（必选） 操作类型，固定为list_vocabulary。
input.prefixstring（可选） 热词列表自定义前缀，如果设定则只返回指定前缀的热词列表。
input.page_indexinteger页码索引，从0开始计数。 默认值：0。
input.page_sizeinteger每页包含数据条数。 默认值：10。

返回体

{
    "output": {
        "vocabulary_list": [
            {
                "gmt_create": "2026-03-02 18:07:38",
                "gmt_modified": "2026-03-02 18:07:38",
                "status": "OK",
                "vocabulary_id": "vocab-ciotest-8e74bef2accf4xxxxxxxx"
            },
            {
                "gmt_create": "2026-02-27 19:04:48",
                "gmt_modified": "2026-02-28 13:40:40",
                "status": "OK",
                "vocabulary_id": "vocab-sifasr-f483ad46e1844fxxxxxxxx"
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "81d51a05-8cdd-45c0-973f-xxxxxxxx"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据。
output.vocabulary_listarray[object]查询到的热词列表。
output.vocabulary_list.vocabulary_idstring热词列表ID。
output.vocabulary_list.gmt_createstring创建时间。
output.vocabulary_list.gmt_modifiedstring修改时间。
output.vocabulary_list.statusstring状态：
  • OK：可调用
  • UNDEPLOYED：不可调用。
usageobject本次请求用量信息。
usage.countinteger固定为1。

查询热词列表

请求体

curl -X POST https://maas.qianwenaiapi.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"
    }
}'
参数类型说明
modelstring（必选） 定制热词模型，固定为speech-biasing。
inputobject（必选） 输入参数对象。
input.actionstring（必选） 操作类型，固定为query_vocabulary。
input.vocabulary_idstring（必选） 需要查询的热词列表ID。

返回体

{
  "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": "赛德克巴莱",
        "weight": 4
      }
    ]
  },
  "usage": {
    "count": 1
  },
  "request_id": "3d461d3f-b2c4-4de5-xxxx"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据。
output.gmt_createstring创建时间。
output.gmt_modifiedstring修改时间。
output.statusstring状态：
  • OK：可调用
  • UNDEPLOYED：不可调用。
output.target_modelstring使用热词列表的语音识别模型，必须与后续调用语音识别接口时使用的模型一致。
output.vocabularyarray[object]查询到的热词列表。
output.vocabulary.textstring热词文本。
output.vocabulary.weightinteger热词权重。
output.vocabulary.langstring待识别音频语种。
usageobject本次请求用量信息。
usage.countinteger固定为1。

更新热词列表

请求体

curl -X POST https://maas.qianwenaiapi.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": "赛德克巴莱", "weight": 4, "lang": "zh"}
        ]
    }
}'
参数类型说明
modelstring（必选） 定制热词模型，固定为speech-biasing。
inputobject（必选） 输入参数对象。
input.actionstring（必选） 操作类型，固定为update_vocabulary。
input.vocabulary_idstring（必选） 需要更新的热词列表ID。
input.vocabularyarray[object]（必选） 新的热词列表，将完全替换原有内容。
input.vocabulary.textstring（必选） 热词文本。 热词文本的语言必须在所选模型的支持范围内，不同模型支持的语言各不相同。 热词用于提升识别的准确率，请使用实际词语而非任意字符组合。 长度限制：含非 ASCII 字符时不超过 15 个字符；纯 ASCII 时空格分隔片段不超过 7 个。
input.vocabulary.weightinteger（必选） 热词权重。常用值：4。 取值范围：[1, 5]。 如果效果不明显，可以适当增加权重，但权重过大可能产生负面效果，导致其他词语识别不准确。
input.vocabulary.langstring（可选） 待识别音频的语言代码。设置后，系统将对指定语种进行热词识别增强。如果无法提前确定语种，可不设置，模型会自动识别语种。 取值范围（因模型而异）：
  • Paraformer：
  • zh: 中文
  • en: 英文
  • ja: 日语
  • yue: 粤语
  • ko: 韩语
  • de：德语
  • fr：法语
  • ru：俄语
  • Fun-ASR：
  • zh: 中文
  • en: 英文
  • ja: 日语

返回体

{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据，固定为空。
usageobject本次请求用量信息。
usage.countinteger更新的热词列表数量，固定为1。

删除热词列表

请求体

curl -X POST https://maas.qianwenaiapi.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"
    }
}'
参数类型说明
modelstring（必选） 定制热词模型，固定为speech-biasing。
inputobject（必选） 输入参数对象。
input.actionstring（必选） 操作类型，固定为delete_vocabulary。
input.vocabulary_idstring（必选） 需要删除的热词列表ID。

返回体

{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据，固定为空。
usageobject本次请求用量信息。
usage.countinteger删除的热词列表数量，固定为1。