Skip to main content

User Word Registration API

By using the User Word Registration API, you can save registered words to any profile. For example, in applications, you can implement word registration functionality for each user by switching profiles for each end user.

Role of Client Applications​

Generally, client applications are expected to implement the following:

  1. Store sets of notation, reading, and class for each end user in a database or similar.
  2. When data is updated, update the profile using the User Word Registration API.
  3. Specify the profile ID when making speech recognition requests.
note

Please keep user word information in the client application and make backups, rather than using profiles as master data whenever possible.

Usage​

For API details, please see the reference. The following sections show usage examples for each use case.

Authorization​

The User Word Registration API specifies APPKEY as authentication information. Please specify Bearer {APPKEY} in the Authorization header when making HTTP requests.

Registering Words​

The endpoint is as follows:

POST https://acp-api.amivoice.com/profilewords/{connection_engine_name}/{profile_id}

For the path parameter {connection_engine_name}, set a speech recognition engine such as -a-general. Also, specify the name of the profile you want to create in the path parameter {profile_id}. For characters that can be used in profile IDs, please see "Usable Characters".

Word registration data is specified in JSON format as follows:

{
  "profilewords": [
    {
      "written": "notation",
      "spoken": "reading"
    },
    {
      "written": "notation",
      "spoken": "reading",
      "classname": "class"
    }
    , ...
  ]
}
info

Please describe character encoding using one of the following methods:

  • Direct description in UTF-8 (e.g., "あ")
  • Unicode escape sequence (e.g., \u3042)

Here's an example using the curl command. This example registers AmiVoice あみぼいす and AOI あおい with a profile ID of test for the 会話_汎用 engine (-a-general):

curl -sS https://acp-api.amivoice.com/profilewords/-a-general/test \
     -H "Authorization: Bearer {APPKEY}" \
     -H "Content-Type: application/json" \
     -d '{"profilewords":[{"written":"AmiVoice","spoken":"あみぼいす"},{"written":"AOI","spoken":"あおい"}]}'

The response is in URL-encoded JSON format as follows:

{"profilewords":[{"written":"AOI","spoken":"\u3042\u304a\u3044"},{"written":"AmiVoice","spoken":"\u3042\u307f\u307c\u3044\u3059"}]}

Using the jq command or JSON parsers in various programming languages, the formatted result looks like this:

{
  "profilewords": [
    {
      "written": "AOI",
      "spoken": "あおい"
    },
    {
      "written": "AmiVoice",
      "spoken": "あみぼいす"
    }
  ]
}
info

Words cannot be added. When adding, please set all words.

Retrieving Registered Words​

The endpoint is as follows, with path parameters the same as Registering Words:

GET https://acp-api.amivoice.com/profilewords/{connection_engine_name}/{profile_id}

Here's an example using the curl command to retrieve a list of words set with a profile ID of test for the 会話_汎用 engine (-a-general):

curl -sS https://acp-api.amivoice.com/profilewords/-a-general/test \
     -H "Authorization: Bearer {APPKEY}"

Decoding and formatting the Unicode-escaped characters in the response looks like this:

{
  "profilewords": [
    {
      "written": "AOI",
      "spoken": "あおい"
    },
    {
      "written": "AmiVoice",
      "spoken": "あみぼいす"
    }
  ]
}

Retrieving Class List​

The endpoint is as follows, with path parameters having the same meaning as Registering Words:

GET https://acp-api.amivoice.com/classnames/{connection_engine_name}

Using the curl command, you can retrieve the list of classes for the specified 会話_汎用 engine (-a-general) as follows:

curl -sS https://acp-api.amivoice.com/classnames/-a-general \
     -H "Authorization: Bearer {APPKEY}"

Response:

{"classnames":["\u56fa\u6709\u540d\u8a5e","\u540d\u524d","\u540d\u524d(\u540d)","\u99c5\u540d","\u5730\u540d","\u4f1a\u793e\u540d","\u90e8\u7f72\u540d","\u5f79\u8077\u540d","\u8a18\u53f7","\u62ec\u5f27\u958b\u304d","\u62ec\u5f27\u9589\u3058","\u5143\u53f7"]}

Decoding and formatting the Unicode-escaped characters in the response looks like this:

{
  "classnames": [
    "固有名詞",
    "名前",
    "名前(名)",
    "駅名",
    "地名",
    "会社名",
    "部署名",
    "役職名",
    "記号",
    "括弧開き",
    "括弧閉じ",
    "元号"
  ]
}

Deleting Words from a Profile​

To delete all words, register an empty array.

curl -sS https://acp-api.amivoice.com/profilewords/-a-general/test \
     -H "Authorization: Bearer {APPKEY}" \
     -H "Content-Type: application/json" \
     -d '{"profilewords": []}'

The response is in URL-encoded JSON format as follows:

{
  "profilewords": []
}