替换词 API v1.1--豆包语音-火山引擎

文档中心

立即注册

导航

替换词 API v1.1

最近更新时间：2025.07.16 20:25:53首次发布时间：2025.07.16 20:25:53

更新日志 ChangeLog:

v1.1

支持传入参数type类型，当type="regex_correct"时，为正则替换词类型 | Support passing the parameter type, where when type = 'regex_correct', it indicates the type for regex replacement words."

v1.0

加入了多个替换词管理模块的POST请求 | Added multiple new POST requests as part of the "Correct Table API"

替换词管理API | Hotword API (ALL For Application)

访问鉴权
鉴权方式说明 https://www.volcengine.com/docs/6369/67268
线上请求地址域名 open.volcengineapi.com
固定公共参数

Region "cn-north-1"
Service "speech_saas_prod"
Version "2023-10-30"

>       3. AKSK获取 https://console.volcengine.com/iam/keymanage/
>       4. 结合文档内api说明调用`ListApplications` `ListCorrectTable` 的例子(*其他语言和使用sdk调用的方式请参考火山鉴权源码[说明](https://www.volcengine.com/docs/6369/185600) 一)

> ```Python
import binascii
import datetime
import hashlib
import hmac
import json
import requests
import urllib

from requests import Response

domain = "open.volcengineapi.com"
region = "cn-north-1"
service = "speech_saas_prod"
contentType = "application/json; charset=utf-8"


def warp_request(
        action: str,
        version: str,
        ak: str,
        sk: str,
        method: str,
        payload: dict,
) -> Response:
    payload['Action'] = action
    payload['Version'] = version
    canonical_query_string = f"Action={action}&Version={version}"
    url = "https://" + domain + "/?" + canonical_query_string
    content_type = "application/json; charset=utf-8"
    payload_sign = get_hmac_encode16(json.dumps(payload))
    headers = get_hashmac_headers(
        domain,
        region,
        service,
        canonical_query_string,
        method,
        "/",
        content_type,
        payload_sign,
        ak,
        sk,
    )

    return requests.request(url=url, method=method, headers=headers, data=json.dumps(payload))


def list_correctword_table(
        app_id: int,
        ak: str,
        sk: str,
) -> requests.Response:
    return warp_request(
        "ListCorrectTable",
        "2023-10-30",
        ak,
        sk,
        "POST",
        {
            "AppID": app_id,
            "PageNumber": 1,
            "PageSize": 10,
            "PreviewSize": 10,
        }
    )


def list_application(ak: str, sk: str) -> requests.Response:
    return warp_request(
        "ListApplications",
        "2021-11-22",
        ak,
        sk,
        "GET",
        {
        }
    )


def get_canonical_query_string(param_dict):
    target = sorted(param_dict.items(), key=lambda x: x[0], reverse=False)
    canonicalQueryString = urllib.parse.urlencode(target)
    return canonicalQueryString


def get_hmac_encode16(data):
    return binascii.b2a_hex(hashlib.sha256(data.encode("utf-8")).digest()).decode(
        "ascii"
    )


def get_volc_signature(secret_key, data):
    return hmac.new(secret_key, data.encode("utf-8"), digestmod=hashlib.sha256).digest()


def get_hashmac_headers(
        domain,
        region,
        service,
        canonicalquerystring,
        httprequestmethod,
        canonicaluri,
        contenttype,
        payloadsign,
        ak,
        sk,
):
    utc_time_sencond = datetime.datetime.utcnow().strftime("%Y%m%dT%H%M%SZ")
    utc_time_day = datetime.datetime.utcnow().strftime("%Y%m%d")
    credentialScope = utc_time_day + "/" + region + "/" + service + "/request"
    headers = {
        "content-type": contenttype,
        "x-date": utc_time_sencond,
    }
    canonicalHeaders = (
            "content-type:"
            + contenttype
            + "\n"
            + "host:"
            + domain
            + "\n"
            + "x-content-sha256:"
            + "\n"
            + "x-date:{}".format(utc_time_sencond)
            + "\n"
    )
    signedHeaders = "content-type;host;x-content-sha256;x-date"
    canonicalRequest = (
            httprequestmethod
            + "\n"
            + canonicaluri
            + "\n"
            + canonicalquerystring
            + "\n"
            + canonicalHeaders
            + "\n"
            + signedHeaders
            + "\n"
            + payloadsign
    )
    stringToSign = (
            "HMAC-SHA256"
            + "\n"
            + utc_time_sencond
            + "\n"
            + credentialScope
            + "\n"
            + get_hmac_encode16(canonicalRequest)
    )
    signingkey = get_volc_signature(
        get_volc_signature(
            get_volc_signature(
                get_volc_signature(sk.encode("utf-8"), utc_time_day), region
            ),
            service,
        ),
        "request",
    )
    signature = binascii.b2a_hex(get_volc_signature(signingkey, stringToSign)).decode(
        "ascii"
    )
    headers[
        "Authorization"
    ] = "HMAC-SHA256 Credential={}/{}, SignedHeaders={}, Signature={}".format(
        ak, credentialScope, signedHeaders, signature
    )
    return headers


if __name__ == "__main__":
    print(
        json.dumps(
            list_correctword_table(
                app_id=0,
                ak="",
                sk="",
            ).json(), indent=4
        )
    )
    print(
        json.dumps(
            list_application(
                ak="",
                sk="",
            ).json(), indent=4
        )
    )

错误码

HTTP status code not starting with 2xx is considered an error;
Detailed Info is listed inside the HTTP response body as
{
    "ResponseMetadata": {
        ...
        "Error": {
            "Code": "xxx",
            "Message": "xxx"
        }
    }
}
"ResponseMetadata.Error.Code" CAN be safely used by client to check error type if any

List User's Applications

Views

Request

Method: GET

Parameter	Type	Must	Argument type	Description
Action	string	Y	query	ListApplications
Version	string	Y	query	2021-11-22

Response

{
  "status": "success",
  "error": null,
  "data": {
    "applications": [
      {
        "id": 86,
        "appid": "10004829",
        "top_account_id": "2100000839",
        "name": "test_lmy123123",
        "description": "Test_lmy111",
        "service_tree_node": "113953",
        "service_tree_path": "|AI-Lab|Speech|PLATFORM|SaaS",
        "created_timestamp": 1631093359000,
        "system": "volcengine",
        "state": "accepted",
        "deactivated": false,
        "alert_user_emails": null,
        "accepted": true,
        "state_comment": "",
        "user_permissions": [
          "admin"
        ],
        "modification": {},
        "workflow_id": ""
      },
      {
        "id": 88,
        "appid": "10004830",
        "top_account_id": "2100000839",
        "name": "test_lmy123123123",
        "description": "1",
        "service_tree_node": "113953",
        "service_tree_path": "|AI-Lab|Speech|PLATFORM|SaaS",
        "created_timestamp": 1631095608000,
        "system": "volcengine",
        "state": "accepted",
        "deactivated": false,
        "alert_user_emails": null,
        "accepted": true,
        "state_comment": "",
        "user_permissions": [
          "admin"
        ],
        "modification": {},
        "workflow_id": ""
      },
      {
        "id": 89,
        "appid": "10004831",
        "top_account_id": "2100000839",
        "name": "test1111",
        "description": "1",
        "service_tree_node": "113953",
        "service_tree_path": "|AI-Lab|Speech|PLATFORM|SaaS",
        "created_timestamp": 1631096047000,
        "system": "volcengine",
        "state": "accepted",
        "deactivated": false,
        "alert_user_emails": null,
        "accepted": true,
        "state_comment": "",
        "user_permissions": [
          "admin"
        ],
        "modification": {},
        "workflow_id": ""
      }
    ]
  }
}

Create Correct Table (file size < 8 MB)

Views

Request

Method: POST

Parameter	Type	Must	Argument type	Description
Content-Type	string	Y	header	multipart/form-data; charset=utf-8
Action	string	Y	body	CreateCorrectTable
Version	string	Y	body	2023-10-30
AppID	int	Y	body	AppID of application
TableName	string	Y	body	Name of the table
File	file	Y	body	Contents of the TXT file; no larger than 8MB; name of the file will be ignored;

Response

{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "CreateCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}" //header中的X-Top-Region参数
    },
    "Result":{
        "AppID": "xxx",
        "CorrectTableID" : "xxx",
        "CorrectTableName" : "xxx",
        "CreateTime": "2022-08-11T14:41:01Z", // UTC YYYY-MM-DD'T'HH:MM:SS'Z'
        "UpdateTime": "2022-08-11T14:41:01Z", // UTC YYYY-MM-DD'T'HH:MM:SS'Z'
        "WordCount": 999       // the line of word
    }
}

// 400 Bad Request
// MissingParameter
{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "CreateCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}", //header中的X-Top-Region参数
        "Error": {
            "Code": "MissingParameter",
            "Message": "The specified parameter File is invalid:  xxx"
        }
    }
}

// 400 Bad Request
// InvalidParameter.CorrectNameDuplicated
{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "CreateCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}", //header中的X-Top-Region参数
        "Error": {
            "Code": "InvalidParameter.CorrectNameDuplicated",
            "Message": "The specified parameter TableName is duplicated: xxx"
        }
    }
}

// 403 Forbidden
// ExceedTotalTableCount
// CorrectTableWrongFormat
{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "CreateCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}", //header中的X-Top-Region参数
        "Error": {
            "Code": "OperationDenied.xxxxxx",
            "Message": "Operation denied because exceeding xxx: xxx"
        }
    }
}

Check Correct Table Name

Description

判断同一appid下词表名是否重复 | Check if the given table name already exists for the same appid

Views

Request

Method: POST

Parameter	Type	Must	Argument type	Description
Content-Type	string	Y	header	application/json; charset=utf-8
Action	string	Y	body	CheckCorrectTableName
Version	string	Y	body	2023-10-30
AppID	int	Y	body	AppID of application
TableName	string	Y	body	Name of the table
type	string	N	body	regex_correct or ""

Response

{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "CheckCorrectTableName",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}" //header中的X-Top-Region参数
    },
    "Result": true
}

// 200 OK
{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "CheckCorrectTableName",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}", //header中的X-Top-Region参数
        "Error": {
            "Code": "InvalidParameter.CorrectNameDuplicated",
            "Message": "The specified parameter TableName is duplicated"
        }
    },
    "Result":false
}

Update Correct Table (< 8 MB)

Views

Request

Method: POST

Parameter	Type	Must	Argument type	Description
Content-Type	string	Y	header	multipart/form-data; charset=utf-8
Action	string	Y	body	UpdateCorrectTable
Version	string	Y	body	2023-10-30
AppID	int	Y	body	AppID of application
TableID	string	Y	body	ID of correct table
TableName	string	N	body	Name of the table, update if not empty
File	string	Y	body	Contents of the TXT file; no larger than 8MB;
type	string	N	body	regex_correct or ""

Response

{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "UpdateCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}" //header中的X-Top-Region参数
    },
    "Result":{
        "AppID": "xxx",
        "CorrectTableID" : "xxx",
        "CorrectTableName" : "xxx",
        "CreateTime": "2022-08-11T14:41:01Z", // UTC YYYY-MM-DD'T'HH:MM:SS'Z'
        "UpdateTime": "2022-08-11T14:41:01Z", // UTC YYYY-MM-DD'T'HH:MM:SS'Z'
        "WordCount": 999       // the line of word
        "ID": 83,
        "CorrectTableID": "xxx",
        "CorrectTableName": "xxx"
    }
}

Update Correct Table has ALL possible error codes and messages that
Create Correct Table and Delete Correct Table have

Delete Correct Table

Views

Request

Method: POST

Parameter	Type	Must	Argument type	Description
Content-Type	string	Y	header	application/json; charset=utf-8
Action	string	Y	body	DeleteCorrectTable
Version	string	Y	body	2023-10-30
AppID	int	Y	body	AppID of application
TableID	string	Y	body	ID of correct table
type	string	N	body	regex_correct or ""

Response

{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "DeleteCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}" //header中的X-Top-Region参数
    },
    "Result":{
        "Message": "success" // 2xx status code is a success; message not important
    }
}

// 404 NotFound
// CorrectTableNotFound
{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "DeleteCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}", //header中的X-Top-Region参数
        "Error": {
            "Code": "OperationDenied.CorrectTableNotFound",
            "Message": "Operation is denied because correct table not found: xxx"
        }
    }
}

List Correct Table

Views

Request

Method: POST

Parameter	Type	Must	Argument type	Description
Content-Type	string	Y	header	application/json; charset=utf-8
Action	string	Y	body	ListCorrectTable
Version	string	Y	body	2023-10-30
AppID	int	Y	body	AppID of application
PageNumber	int		body	Page number; default to 1; invalid value returns empty result
PageSize	int		body	Page size, default to 10; invalid value returns empty result
PreviewSize	int		body	Number of correct words to preview, default to 10
type	string	N	body	regex_correct or ""

Response

{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "ListCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}" //header中的X-Top-Region参数
    },
    "Result":{
        "CorrectTableCount": 1,
        "CorrectTables": [
            {
                "AppID": "xxx",
                "CorrectTableID" : "xxx",
                "CorrectTableName" : "xxx",
                "CreateTime": "2022-08-11T14:41:01Z", // UTC YYYY-MM-DD'T'HH:MM:SS'Z'
                "UpdateTime": "2022-08-11T14:41:01Z", // UTC YYYY-MM-DD'T'HH:MM:SS'Z'
                "WordCount": 999,       // the line of word
                "Preview": ["w0rd|word"] // preview words
            }
        ]
    }
}

Get Correct Table

Request

Method: POST

Parameter	Type	Must	Argument type	Description
Content-Type	string	Y	header	application/json; charset=utf-8
Action	string	Y	body	GetCorrectTable
Version	string	Y	body	2023-10-30
AppID	int	Y	body	AppID of application
TableID	string	Y	body	ID of correct table
type	string	N	body	regex_correct or ""

Response

{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "GetCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}" //header中的X-Top-Region参数
    },
    "Result":{
        "AppID": "xxx",
        "CorrectTableID" : "xxx",
        "CorrectTableName" : "xxx",
        "CreateTime": "2022-08-11T14:41:01Z", // UTC YYYY-MM-DD'T'HH:MM:SS'Z'
        "UpdateTime": "2022-08-11T14:41:01Z", // UTC YYYY-MM-DD'T'HH:MM:SS'Z'
        "WordCount": 999,       // the line of word
        "Preview": ["w0rd|word"] // preview words
    }
}

// 404 NotFound
// CorrectTableNotFound
{
    "ResponseMetadata": {
        "RequestId": "20220214145719010211209131054BC103", //header中的X-Top-Request-Id参数
        "Action": "GetCorrectTable",
        "Version": "2023-10-30",
        "Service": "{Service}",//header中的X-Top-Service参数
        "Region": "{Region}", //header中的X-Top-Region参数
        "Error": {
            "Code": "OperationDenied.CorrectTableNotFound",
            "Message": "Operation is denied because correct table not found: xxx"
        }
    }
}