定制热词HTTP API参考_大模型服务平台百炼(Model Studio) - 大模型服务平台百炼

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

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

重要仅主业务空间支持热词功能，子业务空间暂不支持。

接口地址

新加坡

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/customization

调用时请将{WorkspaceId}替换为真实的业务空间ID。

华北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: 日语

以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

新加坡地域和北京地域的API Key不同，详情请参见获取与配置 API Key。

curl -X POST https://{WorkspaceId}.ap-southeast-1.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。

以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

新加坡地域和北京地域的API Key不同，详情请参见获取与配置 API Key。

curl -X POST https://{WorkspaceId}.ap-southeast-1.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。

以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

新加坡地域和北京地域的API Key不同，详情请参见获取与配置 API Key。

curl -X POST https://{WorkspaceId}.ap-southeast-1.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]（必选）

新的热词列表，将完全替换原有内容。

属性

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: 日语

以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

新加坡地域和北京地域的API Key不同，详情请参见获取与配置 API Key。

curl -X POST https://{WorkspaceId}.ap-southeast-1.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。

以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

新加坡地域和北京地域的API Key不同，详情请参见获取与配置 API Key。

curl -X POST https://{WorkspaceId}.ap-southeast-1.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"
}