Request Parameters

This section explains the parameters to be set when requesting speech recognition with AmiVoice API. Although the transmission methods differ for HTTP and WebSocket interfaces, the parameters that can be set are the same.

List of Parameters

authorization (authentication information) and grammarFileNames (connection engine name) are required. Other parameters are optional. Some parameters are not supported by all interfaces, so please see the table below.

Request parameters share a common structure across the Synchronous HTTP, Asynchronous HTTP, and WebSocket interfaces. This page explains these parameters divided into sections by purpose.

Parameter Name	Description	Required	Sync HTTP	WebSocket	Async HTTP
authorization	Authentication information	●	●	●	●
grammarFileNames	Connection engine name	●	●	●	●
profileId	Profile ID		●	●	●
profileWords	Word registration list		●	●	●
keepFillerToken	Suppression of automatic filler word removal		●	●	●
segmenterProperties	Parameters for speech segment detection and speaker diarization		●	●	● (*1)
extension	Usage aggregation tag		●	●	●
maxDecodingTime	Maximum recognition processing time		●	●	●
maxResponseTime	Maximum response time		●	●	●
maxDecodingRate	Maximum RT		●	●	●
targetResponseTime	Target response time		●	●	●
targetDecodingRate	Target RT		●	●	●
recognitionTimeout	Recognition completion timeout		●	●	●
confidenceLevel	Confidence threshold		●	●	●
completeTimeout	Confirmation wait timeout		● (*2)	● (*2)
wildcardModelPenalty	Wildcard penalty		● (*2)	● (*2)
resultUpdatedInterval	Interval for recognition in progress events			●
noInputTimeout	Speech start timeout			●
loggingOptOut	Change logging or no logging settings				●
contentId	User-defined ID				●
compatibleWithSync	Result format compatibility				●
speakerDiarization	Speaker diarization enable option				●
diarizationMinSpeaker	Minimum estimated number of speakers for diarization				●
diarizationMaxSpeaker	Maximum estimated number of speakers for diarization				●
sentimentAnalysis	Sentiment analysis enable option				●

(*1) In the Asynchronous HTTP interface, parameters related to speaker diarization cannot be used

(*2) Only available with the "音声入力_ルール" engine (-a-rule-input-private)

For information on how to send these request parameters, please see the following sections:

Authentication

authorization

Authentication information

Authentication information must be set to use the API. The authentication information is the [API key] listed on MyPage, or the API key obtained using the API Key Issuance API.

caution

When connecting to the speech recognition server from a browser application, it is recommended to use an API key with an expiration date or IP address restriction to consider the risk of authentication information leakage. For details, please see API Key.

Engine and Language

grammarFileNames

Connection engine name

Specify the speech recognition engine you want to use for the session. Specify one for each session. The values that can be set are listed in the Connection Engine Name table. For details, please see Speech Recognition Engines.

When performing speech recognition using the "音声入力_ルール" engine (-a-rule-input-private) available in AmiVoice API Private, specify the grammar file to use together with the connection engine name in grammarFileNames. For details, please see How to Specify Grammar Files.

Tuning Recognition Results

profileId

Profile ID

A profile is a user-specific data file that exists on the speech recognition server, where users can name and save registered words. The profile ID is an identifier to specify that data file. For details, please see User Dictionary.

profileWords

User Dictionary Word List

You can register words for the user dictionary that will be effective for the session. For word registration with the Hybrid engine, each word is registered in the format "written<half-width space>spoken". If you want to specify a class name, use the format "written<half-width space>spoken<half-width space>class_name". For keyword biasing with the End to End engine, register in the format "written<half-width space>alternative_written<half-width space>biasing_level". The alternative written and biasing level are optional, but if you want to omit only the alternative written, use "written<half-width space><half-width space>biasing_level". For both word registration and keyword biasing, when registering multiple words, separate them with a "|"(half-width vertical bar). The value format is as follows (example when class name is not specified for word registration):

written1 spoken1|written2 spoken2|written3 spoken3|written4 spoken4

When specifying both profileId and profileWords, be sure to specify profileId first.

For details, please see User Dictionary.

keepFillerToken

Suppression of automatic filler word removal

Specify 1 or 0. The default is 0. Specify 1 if you do not want to automatically remove filler words (such as "あー" or "えー") included in the speech recognition results. Also see Automatic Filler Word Removal.

Filler words are surrounded by single-byte "%" before and after the word. Here are examples of filler words:

%あー%
%えー%
%おー%
%えっと%

tip

Please also see the AmiVoice Tech Blog article How to choose whether to display or remove unnecessary words (fillers) with AmiVoice API.

confidenceLevel

Confidence Threshold

Specifies the minimum confidence level required for speech recognition results. If the confidence of the Speech Segment Results is lower than the specified value, the recognition results for that speech segment will be rejected.

The default is 0.1, and the specifiable range is 0.0 to 1.0. Note that setting it to 1.0 will cause most recognition results to be rejected.

caution

The default value may be changed without notice.

Speech Detection, Speaker Diarization, and Language Identification

segmenterProperties

Parameters for speech segment detection

These are parameters to adjust the ease of detecting speech segments, etc. Please try with the default settings first, and then adjust as needed. Parameters available for configuration are as follows.

The default values are common for the Synchronous HTTP interface and WebSocket interface, while the Asynchronous HTTP interface has some different values set. The latter are listed in parentheses.

For details on speech detection, please see Speech Detection.

caution

Default values may be changed without notice.

threshold
- This is the threshold score for determining whether it's a speech segment or not. If the score is greater than or equal to this value, it's considered a speech segment. Lowering this value makes speech segments easier to detect and less likely to be interrupted or cut off at the end, but it also increases the likelihood of false detections. If false detections are noticeable in noisy environments, increase this value.
- The default is 5000 (8000).
preTime
- When a period considered as a speech segment continues for a certain time, it transitions to a state of detecting the speech segment period. This value specifies the length of this "certain time". If short speech segments are not detected or the beginnings of speech segments are easily cut off, decrease this value. If there are many false detections of short noises, increase this value.
- The unit is milliseconds, and the default is 100 (100). Please specify in multiples of 50.
postTime
- When a period considered as non-speech continues for a certain time at the end of a speech segment period, it ends the state of detecting the speech segment period. This value specifies the length of this "certain time". If speech segments are being divided in the middle, increase this value. If two speech segments are being connected, decrease this value.
- The unit is milliseconds, and the default is 550 (800).
preForcedTime
- When transitioning to a state of detecting a speech segment period, this value specifies how far back from the first time considered as speech to set as the start point of the speech segment period. If the beginning of speech segments is easily cut off, increase this value.
- The unit is milliseconds, and the default is 350 (350).
postForcedTime
- When ending the state of detecting a speech segment period, this value specifies how much time after the last time considered as non-speech to include in the speech segment period. If the end of speech segments is easily cut off, increase this value. If the real-time responsiveness of responses is poor, decrease this value.
- The unit is milliseconds, and the default is 350 (350).
powerThreshold
- This is the threshold score when considering volume (power) in determining whether it's a speech segment or not. It needs to be set separately from threshold, and becomes ineffective if set to 0 or less. If the score is below the threshold, it's considered non-speech. If small background sounds are being detected easily, increase this value.
- The default is 100 (100).
decayTime
- You can monotonically decrease the value of postTime after a certain time has passed to make speech segments easier to cut off. This value specifies this "certain time". If the detected speech segment periods are too long, decrease this value.
- The unit is milliseconds, and the default is 5000 (15000).

The recommended values for these parameters in different usage scenarios are as follows:

Parameter	Recommended values applicable to many scenarios (default values for Synchronous HTTP and WebSocket interfaces)	Recommended values for very quiet speech scenarios	Recommended values for scenarios with a lot of BGM, hold music, or non-stationary noise
`threshold`	5000	5000	9000
`preTime`	100	100	100
`postTime`	550	550	550
`preForcedTime`	350	350	350
`postForcedTime`	350	350	350
`powerThreshold`	100	0	100
`decayTime`	5000	5000	5000

Parameters related to speaker diarization

These are parameters related to speaker diarization. They can only be set in Synchronous HTTP and WebSocket interfaces. The following parameters can be set:

useDiarizer
- Setting this to 1 enables speaker diarization in Synchronous HTTP and WebSocket interfaces. It is disabled by default. For details, please see Speaker Diarization.
diarizerAlpha
- This parameter controls the ease of appearance of new speakers in speaker diarization for Synchronous HTTP and WebSocket interfaces. Larger values make new speakers more likely to appear, while smaller values make new speakers less likely to appear. diarizerAlpha=0 is special and is treated as if 1e-30 was specified. However, for engines that support 8kHz audio, for example, when using the general-purpose engine (-a-general) and sending 8kHz audio, it is treated as if 1e-10 was specified. If nothing is set, it is treated as if diarizerAlpha=0 was specified.
diarizerTransitionBias
- This parameter controls the ease of speaker transitions in speaker diarization for Synchronous HTTP and WebSocket interfaces. Larger values make speaker transitions more likely, while smaller values make speaker transitions less likely. diarizerTransitionBias=0 is special and is treated as if 1e-20 was specified. If nothing is set, it is treated as if diarizerTransitionBias=0 was specified.

Parameters for language identification function

useLid
- Enables the function to obtain language labels in Word-Level Results. Disabled by default.
- Supported languages are Japanese (ja), English (en), Chinese (zh), Korean (ko), and Thai (th). The language of each word in the recognition results is estimated from the languages set in the parameter. For example, to perform language identification between Japanese and English, set useLid=ja,en.
- If only one language is specified, all words will be labeled with that language.
- Speech recognition and the language identification function using this parameter are processed separately. Therefore, there may be cases where the words obtained from speech recognition and the language information obtained do not match.
- For multilingual End to End engines, language labels can be obtained without setting this parameter, but if this parameter is set, the language labels obtained according to this parameter setting will be reflected in the recognition results.

How to Set Parameters

Write the parameter settings following segmenterProperties=. When setting multiple parameters simultaneously, separate each parameter with a single-byte space.

Setting example for Synchronous HTTP interface using curl command

URL encode the single-byte space inserted when setting multiple parameters to %20.

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={API_KEY} \
     -F d="grammarFileNames=-a-general segmenterProperties=threshold=4000%20postTime=600" \
     -F a=@test.wav

Setting example for WebSocket interface

Enclose the entire set of parameters for segmenterProperties in double quotes like "...".

s 16K -a-general authorization={API_KEY} segmenterProperties="preTime=200 useDiarizer=1 diarizerAlpha=1e-20"

Controlling Processing Time and Response

maxDecodingTime

Maximum recognition processing time

A parameter that forcibly interrupts speech recognition processing when the following condition is met:

\text{Recognition processing time so far} > \text{maxDecodingTime}

The unit is milliseconds. The default is 0, and when it's 0, this function is disabled.

maxResponseTime

Maximum response time

A parameter that forcibly interrupts speech recognition processing when the following condition is met:

\text{Recognition processing time so far} > \text{Time of input audio} + \text{maxResponseTime}

The unit is milliseconds. This function is only effective when performing speech recognition while recording in real-time, and is ineffective for batch processing using pre-recorded audio data. Also, note that it only activates after receiving all audio data.

The default is 0, and when it's 0, this function is disabled.

maxDecodingRate

Maximum RT

A parameter that forcibly interrupts speech recognition processing when the following condition is met:

\text{Recognition processing time so far} > \text{Time of input audio} \times \text{maxDecodingRate}

This function is only effective for batch processing using pre-recorded audio data, and is ineffective when performing speech recognition while recording in real-time. Also, note that it only activates after receiving all audio data.

The default is -1, and when it's a negative value, this function is disabled.

RT (Real Time factor) is a value that represents the processing speed of speech recognition, calculated as RT = Recognition processing time / Time of input audio.

targetResponseTime

Target Response Time

Calculate "Provisional RT" as $\text{Provisional RT} = \frac{\text{Recognition processing time so far}}{\text{Duration of input audio so far}}$ , and

\text{Provisional RT} \approx \frac{\text{Duration of input audio so far} + \text{targetResponseTime}}{\text{Duration of input audio so far}}

This function dynamically adjusts the balance between speech recognition processing speed and accuracy during recognition. The unit is milliseconds. This function is not activated when the "Duration of input audio so far" is less than 1 second, or when the "Recognition processing time so far" is less than the "Duration of input audio so far" (i.e., when "Provisional RT" is not 1 or greater).

This function is only effective when performing speech recognition while recording in real-time, and is ineffective for batch processing using pre-recorded audio data.

The default value is 0, and when set to 0, this function is disabled.

targetDecodingRate

Target RT

Calculate "Provisional RT" as $\text{Provisional RT} = \frac{\text{Recognition processing time so far}}{\text{Duration of input audio so far}}$ , and

\text{Provisional RT} \approx \text{targetDecodingRate}

This function dynamically adjusts the balance between speech recognition processing speed and accuracy during recognition. This function is not activated when the "Duration of input audio so far" is less than 1 second, or when the "Recognition processing time so far" is less than the "Duration of input audio so far" (i.e., when "Provisional RT" is not 1 or greater).

This function is only effective for batch processing using pre-recorded audio data, and is ineffective when performing speech recognition while recording in real-time.

The default value is -1, and when set to a negative value, this function is disabled.

recognitionTimeout

Recognition Completion Timeout

This function forcibly interrupts the speech recognition process if it does not complete within a specified time (= recognitionTimeout) and allows obtaining intermediate results of speech recognition at that point. The unit is milliseconds. When this function is enabled, if speech recognition is successful in one speech segment, recognition processing will not be performed for subsequent speech segments even within the time set by recognitionTimeout. However, if no recognition result is obtained, such as when the entire speech segment is recognized as a filler and rejected as a result of speech recognition processing, recognition processing for the next speech segment will continue.

For Synchronous HTTP interface and Asynchronous HTTP interface, the recognitionTimeout count starts from the point when the server begins receiving audio from the client. For WebSocket interface, it starts from the point when the beginning of the first speech segment is detected. Note that the duration of recognitionTimeout is the time taken for recognition processing, not the duration of the audio data.

The default value is 0, and when set to 0, this function is disabled.

This function is effective in cases where it is important to find a speech segment containing valid recognition results as quickly as possible, such as in a question-and-answer voicebot, and where recognition processing is not necessary for subsequent speech segments. If you enable this function and find that the speech segments are interrupted mid-speech, resulting in incomplete recognition results, adjust the postTime in segmenterProperties.

tip

For detailed behavior and specific usage of recognitionTimeout and noInputTimeout, please see the tech blog "AmiVoice API Update Explanation: New Parameters for Voicebots Reduce Response Wait Times".

resultUpdatedInterval

Interval for recognition in progress events

This is only valid for the WebSocket interface.

Specifies the interval in milliseconds at which recognition in progress events are issued.

Setting it to 0 will not issue recognition in progress events.
It issues recognition in-progress events every time the specified time elapses. If the interim recognition result is not updated during the specified time, the previous interim recognition result with a "." added to the end will be sent. If a value including a fraction less than 100 is specified, it will be treated as if the value rounded up to a multiple of 100 was specified.

noInputTimeout

Speech Start Timeout

This is only valid for the WebSocket interface.

This function forcibly ends the speech recognition session and cancels all subsequent recognition processing if no speech segment is detected for a certain period (= noInputTimeout). The unit is milliseconds. The length of this time is the time taken for speech recognition processing, not the duration of the audio data.

When the session ends, the client receives "e timeout occurred" error.

The default value is 0, and when set to 0, this function is disabled.

tip

Operations and Management

extension

Usage aggregation tag

When sharing the same AmiVoice API account across multiple systems, environments, end-users, etc., you can set an aggregation tag to obtain usage for arbitrary attributes. For details, please see Usage Aggregation Tags.