定制热词HTTP API参考 - 阿里云百炼

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

新加坡地域的子业务空间暂不支持热词功能。

接口地址

华北2（北京）
新加坡

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/customization调用时请将{WorkspaceId}替换为真实的Workspace ID。

阿里云百炼为华北2（北京）、新加坡地域推出了业务空间专属域名，能够为推理请求提供卓越的性能和更高的稳定性，建议迁移至新域名：

华北2（北京）地域：从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
新加坡地域：从 dashscope-intl.aliyuncs.com 迁移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。

请求头

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

创建热词列表

请求体

modelstring（必选）定制热词模型，固定为speech-biasing。inputobject（必选）输入参数对象。

属性

action string（必选）操作类型，固定为create_vocabulary。target_model string（必选）使用热词列表的语音识别模型，必须与后续调用语音识别接口时使用的模型一致。prefix string（必选）热词列表自定义前缀，仅允许数字和小写字母，长度不超过10个字符。vocabulary array[object]（必选）热词列表数组。

属性

text string（必选）热词文本。热词文本的语言必须在所选模型的支持范围内，不同模型支持的语言各不相同。热词用于提升识别的准确率，请使用实际词语而非任意字符组合。长度限制：含非 ASCII 字符时不超过 15 个字符；纯 ASCII 时空格分隔片段不超过 7 个。weight integer（必选）热词权重。常用值：4。取值范围：[1, 5]。如果效果不明显，可以适当增加权重，但权重过大可能产生负面效果，导致其他词语识别不准确。lang string（可选）待识别音频的语言代码。设置后，系统将对指定语种进行热词识别增强。如果无法提前确定语种，可不设置，模型会自动识别语种。取值范围（因模型而异）：

Paraformer：
- zh: 中文
- en: 英文
- ja: 日语
- yue: 粤语
- ko: 韩语
- de：德语
- fr：法语
- ru：俄语
Fun-ASR：
- zh: 中文
- en: 英文
- ja: 日语

以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。新加坡地域和北京地域的API Key不同，详情请参见获取与配置 API Key。

curl -X POST https://{WorkspaceId}.cn-beijing.maas.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": "赛德克巴莱", "weight": 4}
        ]
    }
}'

返回体

request_idstring本次调用的唯一标识符。outputobject模型返回的数据。

属性

vocabulary_idstring创建的热词列表ID。

usageobject本次请求用量信息。

属性

count integer创建的热词列表数量，固定为1。

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

批量查询热词列表

请求体

modelstring（必选）定制热词模型，固定为speech-biasing。inputobject（必选）输入参数对象。

属性

action string（必选）操作类型，固定为list_vocabulary。prefix string（可选）热词列表自定义前缀，如果设定则只返回指定前缀的热词列表。page_index integer页码索引，从0开始计数。默认值：0。page_size integer每页包含数据条数。默认值：10。

curl -X POST https://{WorkspaceId}.cn-beijing.maas.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
    }
}'

返回体

request_idstring本次调用的唯一标识符。outputobject模型返回的数据。

属性

vocabulary_listarray[object]查询到的热词列表。

属性

vocabulary_idstring热词列表ID。gmt_createstring创建时间。gmt_modifiedstring修改时间。statusstring状态：

OK：可调用
UNDEPLOYED：不可调用。

usageobject本次请求用量信息。

属性

count integer固定为1。

{
    "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"
}

查询热词列表

请求体

modelstring（必选）定制热词模型，固定为speech-biasing。inputobject（必选）输入参数对象。

属性

action string（必选）操作类型，固定为query_vocabulary。vocabulary_id string（必选）需要查询的热词列表ID。

curl -X POST https://{WorkspaceId}.cn-beijing.maas.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"
    }
}'

返回体

request_idstring本次调用的唯一标识符。outputobject模型返回的数据。

属性

gmt_createstring创建时间。gmt_modifiedstring修改时间。statusstring状态：

OK：可调用
UNDEPLOYED：不可调用。

target_model string使用热词列表的语音识别模型，必须与后续调用语音识别接口时使用的模型一致。vocabularyarray[object]查询到的热词列表。

属性

text string热词文本。weight integer热词权重。lang string待识别音频语种。

usageobject本次请求用量信息。

属性

count integer固定为1。

{
  "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"
}

更新热词列表

请求体

modelstring（必选）定制热词模型，固定为speech-biasing。inputobject（必选）输入参数对象。

属性

action string（必选）操作类型，固定为update_vocabulary。vocabulary_id string（必选）需要更新的热词列表ID。vocabulary array[object]（必选）新的热词列表，将完全替换原有内容。

属性

Paraformer：
- zh: 中文
- en: 英文
- ja: 日语
- yue: 粤语
- ko: 韩语
- de：德语
- fr：法语
- ru：俄语
Fun-ASR：
- zh: 中文
- en: 英文
- ja: 日语

curl -X POST https://{WorkspaceId}.cn-beijing.maas.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": "赛德克巴莱", "weight": 4, "lang": "zh"}
        ]
    }
}'

返回体

request_idstring本次调用的唯一标识符。outputobject模型返回的数据，固定为空。usageobject本次请求用量信息。

属性

count integer更新的热词列表数量，固定为1。

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

删除热词列表

请求体

modelstring（必选）定制热词模型，固定为speech-biasing。inputobject（必选）输入参数对象。

属性

action string（必选）操作类型，固定为delete_vocabulary。vocabulary_id string（必选）需要删除的热词列表ID。

curl -X POST https://{WorkspaceId}.cn-beijing.maas.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"
    }
}'

返回体

request_idstring本次调用的唯一标识符。outputobject模型返回的数据，固定为空。usageobject本次请求用量信息。

属性

count integer删除的热词列表数量，固定为1。

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

​接口地址

​请求头

​创建热词列表

请求体

返回体

​批量查询热词列表

请求体

返回体

​查询热词列表

请求体

返回体

​更新热词列表

请求体

返回体

​删除热词列表

请求体

返回体

接口地址

请求头

创建热词列表

批量查询热词列表

查询热词列表

更新热词列表

删除热词列表