Logo
Login
Cloud APIOn DeviceOn-Prem
Hotwords API

Cloud API (Json)

Hotwords API protocol (Json Format)

Create Hotwords Database

Basic Information

Path： /v1/hotwords

Method： POST

**API Description： ** Upload a hotword list file to create a hotword database. There is no upper limit to the number of hotwords database you can create. No more than 30 characters per hotword/pronunciation when manually extracting hotwords. A database shall not exceed 20000 terms.

When extracting hotwords automatically, the text content does not exceed 1,000,000 characters (Currently, only Chinese, Chinese-English mixed languages are supported).

For hot words that do not meet the requirements, the platform will automatically filter them out. Hot words in the following cases will be filtered out:

  • Consisting of only one column or two columns (applicable only to Japanese and Japanese-English mixed languages)
  • Categories not selected from the drop-down values
  • Containing only punctuation marks
  • Exceeding the character limit
  • Including emojis or special symbols
  • Empty content
  • Duplicate entries
  • Pronunciations not entered in hiragana or full-width katakana
  • When there are more than one column (applicable only to English, Chinese, and Chinese-English mixed languages)

Request Parameters

Body（json）

NameTypeRequiredDescriptionDefault Value
nameStringNoHotwords database namenone
lang_typeStringYesLanguage code. Refer to Developer Guides - Language SupportNull
wordsList<string>YesHotwords list file
Set different formats according to the language.
Japanese/Japanese-English mixed: ["writing, pronunciation, category", "writing, pronunciation, category", ...]
Chinese/Chinese-English mixed/English: ["writing", "writing", ...]		Null
auto_extractionBooleanNoWhether to automatically extract keywords from the content in the hotwords list file. Currently only Chinese and Chinese-English mixed languages are supported.false
idstringNoHotwords database ID
The following characters are supported: digits, letters (case-insensitive), underscores, and hyphens ([a-zA-Z0-9_-]). The length must not exceed 150 characters.
If no ID is specified, the system will automatically generate an ID.		Null

Return Parameters

NameTypeDescription
statusStringStatus code
messageStringStatus code description
dataObjectData
├─ idStringHotwords database ID

Example of request

Manually extract hotwords, each element in the list is a hotword entry.

curl --location 'https://api.voice.dolphin-ai.jp/v1/hotwords' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "name": "test",
    "lang_type": "ja-JP",
    "words": ["早稲田大学,ワセダダイガク,固有名詞","新横浜,シンヨコハマ,地名"]
}'

Automatic extraction of hotwords, the content of the chapter can be one element or multiple elements, you need to set the parameter auto_extraction to true.

curl --location 'https://api.voice.dolphin-ai.jp/v1/hotwords' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "name": "test1",
    "lang_type": "zh-cmn-Hans-CN",
    "auto_extraction": true,
    "words": ["中国第40次南极考察内陆队北京时间16日在中山站举行出征仪式，29名队员将分别前往泰山站、昆仑站和格罗夫山地区，开展相关科学考察。中国第40次南极考察由自然资源部组织。这是中国首次派出3艘船执行南极考察任务，即雪龙号、雪龙二号和天惠轮。","其中，天惠轮目前正在罗斯海新站卸运建站物资，雪龙二号正在前往新西兰利特尔顿港。本次考察的一个重要方面是开展国际南极科学前沿领域合作研究，并与多国开展后勤保障方面的国际合作。"]
}'

Example of return

{
    "status": "000000",
    "message": "Success",
    "data": {
        "id": "HW3D0F1284"
    }
}

Delete Hotwords Database

Basic Information

Path： /v1/hotwords/{hotwords_id}

Method： DELETE

API Description： Delete the hotwords database with the specified ID. Only the database that is not currently being used for recognition requests can be deleted.

Example of request

curl --location --request DELETE 'https://api.voice.dolphin-ai.jp/v1/hotwords/HWA3B0FD4F' \
--header 'Authorization: ••••••'

Example of return

{
    "status": "00000",
    "message": "success",
    "data": null
}

Return Parameters

NameTypeDescription
statusStringStatus code
messageStringStatus code description
dataObjectNull

Get a List of Hotword Database Information

Basic Information

Path： /v1/hotwords

Method： GET

API Description： Get information on all hotwords databases.

Request Parameters

NameTypeRequiredDescriptionDefault Value
nameStringNoHotwords database name or hotwords database IDnone
lang_typeStringNoLanguage codenone
page_sizeIntNoNumber of data per page, maximum 10010
page_indexIntNoPage number1

Return Parameters

NameTypeDescription
statusStringStatus code
messageStringStatus code description
dataObjectData
├─ amountIntThe number of hotwords database under the filtering conditions (such as hotwords database name or ID, language filtering)
├─ usedIntTotal number
├─ listObject[]
├─├─ idStringHotwords database ID
├─├─ nameStringHotwords database name
├─├─ lang_typeStringLanguage code
├─├─ statusIntStatus 0: unused 1: in use
├─├─ amountIntNumber of entries
├─├─ update_timeStringLast modified time

Example of request

curl --location 'https://api.voice.dolphin-ai.jp/v1/hotwords' \
--header 'Authorization: ••••••'

Example of return

{
    "status": "000000",
    "message": "Success",
    "data": {
        "list": [
            {
                "id": "HWF21FA445",
                "name": "xxx",
                "lang_type": "ja-JP",
                "status": 0,
                "amount": 2,
                "updated_time": "2025-02-10 17:23:01"
            }
        ],
        "amount": 13,
        "used": 13
    }
}

Get Hotwords Database Information

Basic Information

Path： /v1/hotwords/{hotwords_id}

Method： GET

API Description： Get information about the hotwords database with the specified ID.

Return Parameters

NameTypeDescription
statusStringStatus code
messageStringStatus code description
dataObjectData
├─ idStringHotwords database ID
├─ nameStringHotwords database name
├─ lang_typeStringLanguage code
├─ statusIntStatus
0: unused
1: in use
├─ update_timeStringLast modified time
├─ wordsList<string>Hotwords list
├─ amountIntNumber of entries

Example of request

curl --location 'https://api.voice.dolphin-ai.jp/v1/hotwords/HW09A3ECA7' \
--header 'Authorization: ••••••'

Example of return

{
    "status": "000000",
    "message": "Success",
    "data": {
        "id": "HW09A3ECA7",
        "name": "123",
        "lang_type": "ja-JP",
        "status": 0,
        "updated_time": "2025-01-03 13:12:34",
        "words": [
            "早稲田大学,ワセダダイガク,固有名詞",
            "新横浜,シンヨコハマ,地名"
        ],
        "amount": 2
    }
}

Modify Hotwords Database Information

Basic Information

Path： /v1/hotwords/{hotwords_id}

Method： PUT

API Description： Modify the name of an existing hotword database or hotword list. Note：When modifying the hotwords list, all hotwords in the database will be overwritten by the new list, if you need to add more hotwords, please use the Add Hotword Entry API.

Request Parameters

Body（json）

NameTypeRequiredDescriptionDefault Value
nameStringNoHotwords database namenone
wordsList<string>NoHotwords listnone
auto_extractionBooleanNoWhether to automatically extract keywords from the content in the hotwords list. Only Chinese and Chinese-English mixed languages are supported.false

Return Parameters

NameTypeDescription
statusStringStatus code
messageStringStatus code description
dataObjectData
├─ idStringHotwords database ID

Example of request

curl --location --request PUT 'https://api.voice.dolphin-ai.jp/v1/hotwords/HWCFCB0FF0' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "name": "123",
    "words": ["早稲田大学,ワセダダイガク,固有名詞"]
}'

In the above example, both the name of the database and the content of the hotwords are changed. If you only need to change the name of the database, you don't need to pass the words parameter; vice versa.

Example of return

{
    "status": "000000",
    "message": "Success",
    "data": {
        "id": "HWCFCB0FF0"
    }
}

Add Hotwords Entry

Basic Information

Path： /v1/hotwords/{hotwords_id}

Method： POST

API Description： Add entries to an existing database. Each entry should not exceed 30 characters, and a database should not exceed 20000 entries.

Return Parameters

Body（json）

NameTypeRequiredDescriptionDefault Value
wordsList<string>YesHotwords listrequired
auto_extractionBooleanNoWhether to automatically extract keywords from the content of the hotwords list (currently only supports Chinese, Chinese-English mixed languages)false

Return Parameters

NameTypeDescription
statusStringStatus code
messageStringStatus code description
dataIntNumber of entries for hotwords in the current database

Example of request

curl --location 'https://api.voice.dolphin-ai.jp/v1/hotwords/HW300184B2' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "words": ["早稲田大学,ワセダダイガク,固有名詞"]
}'

Example of return

{
    "status": "000000",
    "message": "Success",
    "data": 2
}

Delete Hotwords Entry

Basic Information

Path： /v1/hotwords/{hotwords_id}

Method： DELETE

API Description： Delete the specified hotwords entry in the hotwords database with the specified ID. Note: When the request does not contain a request body (Body), the entire hotwords database will be deleted.

Request Parameters

Body（json）

NameTypeRequiredDescriptionDefault Value
wordsList<string>YesList of hotwords to be deletedrequired

Return Parameters

NameTypeDescription
statusStringStatus code
messageStringStatus code description
dataIntNumber of entries for hotwords in the current database

Example of request

curl --location --request DELETE 'https://api.voice.dolphin-ai.jp/v1/hotwords/HWCFCB0FF0' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{"words": ["早稲田大学,ワセダダイガク,固有名詞"]}'

Example of return

{
    "status": "000000",
    "message": "Success",
    "data": 4
}

Download Hotwords Database

Basic Information

Path： /v1/hotwords/download/{hotwords_id}

Method： GET

API Description： Download the specified hotwords database.

Example of request

curl --location 'https://api.voice.dolphin-ai.jp/v1/hotwords/download/HWF8C024CA' \
--header 'Authorization: ••••••'

Example of return

Starting from the second line, enter one hot word per line. Note: For hot words in Japanese or mixed Japanese-English languages, you need to maintain 'writing, pronunciation, class' with three items separated by commas. If any item is missing, it is considered an invalid hot word. For hot words in other languages, only the 'writing' needs to be maintained.
インスパイア,コンニチハ,固有名詞
カタカナ,コンニチハ,固有名詞
プレゼント,コンニチハ,固有名詞

H5/JS SDK

Short Speech Recognition H5/JS SDK

Cloud API (Form-Data)

Hotwords API protocol (Form-Data Format)

On this page

Create Hotwords Database
Basic Information
Request Parameters
Return Parameters
Delete Hotwords Database
Basic Information
Return Parameters
Get a List of Hotword Database Information
Basic Information
Request Parameters
Return Parameters
Get Hotwords Database Information
Basic Information
Return Parameters
Modify Hotwords Database Information
Basic Information
Request Parameters
Return Parameters
Add Hotwords Entry
Basic Information
Return Parameters
Return Parameters
Delete Hotwords Entry
Basic Information
Request Parameters
Return Parameters
Download Hotwords Database
Basic Information