User Dictionary (Word Registration and Keyword Biasing)

AmiVoice API has a user dictionary feature. For words that are not recognized or difficult to recognize, you can use "word registration" for the Hybrid engine and "keyword biasing(boosting)" for the End to End engine.

Here, we first introduce a procedure to easily try out the user dictionary function.

Quick Start

note

To run the Python sample code, you need the requests library. Save the following code with a file name such as quickstart.py.

python -m pip install requests

Run it with the following command.

python quickstart.py

Depending on your environment, use python3 or py instead of python.

Register a User Dictionary

You can use the User Dictionary Registration API or register a user dictionary from the MyPage. Here, we will register "とりぷるだぶる" to be recognized as "WWW" for the "会話_汎用" engine (-a-general) as follows:

macOS / Linux
Windows (PowerShell)
Windows (Command Prompt)
MyPage
Python

Replace {API_key} with your account's API key.
Replace {profile_id} with any profile ID you want to use. For example, if you want to use a profile ID of "test", replace {profile_id} in the following with "test".

curl https://acp-api.amivoice.com/profilewords/-a-general/{profile_id} \
     -H "Authorization: Bearer {API_key}" \
     -H "Content-Type: application/json" \
     -d '{"profilewords":[{"written":"WWW","spoken":"とりぷるだぶる"}]}' | jq

note

If the curl command is not installed, download the package for your OS from https://curl.se/ or use a package manager to install curl.
The About Result Text is Unicode escaped. In the above command, jq is used to format the response for better readability. If jq is not installed, try running without the | jq part. You can download the jq command package for your OS from https://stedolan.github.io/jq/ or install it using a package manager.

Replace {API_key} with your account's API key.
Replace {profile_id} with any profile ID you want to use. For example, if you want to use a profile ID of "test", replace {profile_id} in the following with "test".

curl.exe https://acp-api.amivoice.com/profilewords/-a-general/{profile_id} `
     -H "Authorization: Bearer {API_key}" `
     -H "Content-Type: application/json" `
     -d '{"profilewords":[{"written":"WWW","spoken":"とりぷるだぶる"}]}' | jq

note

In PowerShell, curl is an alias for Invoke-WebRequest, so please explicitly use curl.exe. Windows 10 version 1803 and later include curl.exe by default. If it's not included, please install it from https://curl.se/.
The About Result Text is Unicode escaped. In the above command, jq is used to format the response for better readability. If jq is not installed, try running without the | jq part. You can download the jq command package for your OS from https://stedolan.github.io/jq/ or install it using a package manager.

Replace {API_key} with your account's API key.
Replace {profile_id} with any profile ID you want to use. For example, if you want to use a profile ID of "test", replace {profile_id} in the following with "test".

curl https://acp-api.amivoice.com/profilewords/-a-general/{profile_id} ^
     -H "Authorization: Bearer {API_key}" ^
     -H "Content-Type: application/json" ^
     -d "{""profilewords"":[{""written"":""WWW"",""spoken"":""とりぷるだぶる""}]}" | jq

note

Windows 10 version 1803 and later include curl by default. If it's not included, please install it from https://curl.se/.
In Command Prompt, you cannot use ' (single quotation) to specify JSON strings, so use " (double quotation) instead. Also, escape the double quotations used internally (use "" or \").
The About Result Text is Unicode escaped. In the above command, jq is used to format the response for better readability. If jq is not installed, try running without the | jq part. You can download the jq command package for your OS from https://stedolan.github.io/jq/ or install it using a package manager.

Replace {API_key} with your account's API key.
Replace {profile_id} with any profile ID you want to use. For example, if you want to use a profile ID of "test", replace {profile_id} in the following with "test".

import requests
import json

dgn = "-a-general"    # Specify the connection engine name
pid = "{profile_id}"  # Replace with the profile ID you want to use
api_key = "{API_key}" # Replace with your actual API key

endpoint = f"https://acp-api.amivoice.com/profilewords/{dgn}/{pid}"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
data = {
    "profilewords": [
        {"written": "WWW", "spoken": "とりぷるだぶる"}
    ]
}

# Send POST request
response = requests.post(endpoint, headers=headers, json=data)

# Check the response status code
if response.status_code == 200:
    # Display JSON response
    response_json = response.json()
    print(json.dumps(response_json, indent=4, ensure_ascii=False))
else:
    print(f"Error: {response.status_code}{response.text}")

Prepare an Audio File

Prepare an audio file you want to transcribe. You can use the following sample audio (www.wav) as is.

For supported audio file formats, please see Audio Formats.

Execute Speech Recognition

Execute the following. Replace {API_key} with your account's API key, {profile_id} with the profile ID of the profile you want to use, and www.wav with the path to the audio file you want to use.

curl (macOS / Linux)
curl (Windows PowerShell)
curl (Windows Command Prompt)
Python

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={API_key} \
     -F d="grammarFileNames=-a-general profileId=:{profile_id}" \
     -F a=@www.wav | jq

note

If the curl command is not installed, download the package for your OS from https://curl.se/ or use a package manager to install curl.
The About Result Text is Unicode escaped. In the above command, jq is used to format the response for better readability. If jq is not installed, try running without the | jq part. You can download the jq command package for your OS from https://stedolan.github.io/jq/ or install it using a package manager.

curl.exe https://acp-api.amivoice.com/v1/recognize `
     -F u={API_key} `
     -F d="grammarFileNames=-a-general profileId=:{profile_id}" `
     -F a=@www.wav | jq

note

In PowerShell, curl is an alias for Invoke-WebRequest, so please explicitly use curl.exe. Windows 10 version 1803 and later include curl.exe by default. If it's not included, please install it from https://curl.se/.
The About Result Text is Unicode escaped. In the above command, jq is used to format the response for better readability. If jq is not installed, try running without the | jq part. You can download the jq command package for your OS from https://stedolan.github.io/jq/ or install it using a package manager.

curl https://acp-api.amivoice.com/v1/recognize ^
     -F u={API_key} ^
     -F d="grammarFileNames=-a-general profileId=:{profile_id}" ^
     -F a=@www.wav | jq

note

Windows 10 version 1803 and later include curl by default. If it's not included, please install it from https://curl.se/.
The About Result Text is Unicode escaped. In the above command, jq is used to format the response for better readability. If jq is not installed, try running without the | jq part. You can download the jq command package for your OS from https://stedolan.github.io/jq/ or install it using a package manager.

import requests

api_key = "{API_key}"
pid = "{profile_id}"  # e.g., test

with open("www.wav", "rb") as f:
    response = requests.post(
        "https://acp-api.amivoice.com/v1/recognize",
        data={
            "d": f"grammarFileNames=-a-general profileId=:{pid}",
            "u": api_key
        },
        files={"a": f}
    )

print(response.json())

Check the Result

If successful, JSON like the following will be returned. The transcription result is included in the text field.

{
  "results": [
    {
      "tokens": [ ... ],
      "confidence": 0.94,
      "starttime": 500,
      "endtime": 2084,
      "tags": [],
      "rulename": "",
      "text": "WWW"
    }
  ],
  "utteranceid": "20260611/18/019eb5f848ac0a3013ba94cb_20260611_181648",
  "text": "WWW",
  "code": "",
  "message": ""
}

For details on the response content, please see Speech Recognition Result Format.

Next Steps

In the case of the Hybrid engine, by default, the speech recognition engine can only recognize words that are pre-registered. Therefore, to recognize proper nouns or other words unknown to the engine, you need to additionally register the information for those words. This function is called "word registration".

On the other hand, the End to End engine has a different speech recognition mechanism from the Hybrid engine and does not have "pre-registered words". To recognize words that are not recognized or difficult to recognize, you perform "keyword biasing" to increase the frequency of occurrence of those words.

This section explains the following in order:

Please see the following for API references:

note

User dictionaries are not supported for some languages. For details, please see the Supported Languages by AmiVoice API.

tip

AmiVoice Tech Blog also introduces various tips for user dictionary.

Quick Start​

Register a User Dictionary

Prepare an Audio File

Execute Speech Recognition

Check the Result

Next Steps​

Quick Start

Next Steps