リクエストパラメータ

AmiVoice API で音声認識をリクエストするときに設定するパラメータについて説明します。HTTP、WebSocket インタフェースでそれぞれ送信方法が異なりますが、設定できるパラメータは同じです。

パラメータの一覧

authorization(認証情報)とgrammarFileNames(接続エンジン名)は必須です。その他のパラメータはオプションです。インタフェース毎に対応していないものもありますので、下記の表を参照してください。

パラメータ名	説明	必須	同期HTTP	WebSocket	非同期HTTP
authorization	認証情報	●	●	●	●
grammarFileNames	接続エンジン名	●	●	●	●
profileId	プロファイル ID		●	●	●
profileWords	単語登録リスト		●	●	●
keepFillerToken	フィラー単語（不要語）の自動削除の抑制		●	●	●
segmenterProperties	発話区間検出・話者ダイアライゼーションのパラメータ		●	●	● （*１）
extension	使用量集計タグ		●	●	●
maxDecodingTime	最大認識処理時間		●	●	●
maxResponseTime	最大応答時間		●	●	●
maxDecodingRate	最大 RT		●	●	●
targetResponseTime	目標応答時間		●	●	●
targetDecodingRate	目標 RT		●	●	●
recognitionTimeout	認識完了タイムアウト		●	●	●
resultUpdatedInterval	認識中イベントの間隔			●
noInputTimeout	発話開始待ちタイムアウト			●
loggingOptOut	ログ保存のあり、なしの変更				●
contentId	ユーザー定義 ID				●
compatibleWithSync	結果フォーマットの互換性				●
speakerDiarization	話者ダイアライゼーションの有効化オプション				●
diarizationMinSpeaker	話者ダイアライゼーションの最小推定話者人数				●
diarizationMaxSpeaker	話者ダイアライゼーションの最大推定話者人数				●
sentimentAnalysis	感情分析の有効化オプション				●

（*１）非同期 HTTP インタフェースでは、話者ダイアライゼーションに関するパラメータは使えません

これらのリクエストパラメータの送信方法については、次のセクションを参照してください。

• 同期 HTTP インタフェース
• 非同期 HTTP インタフェース
• WebSocket インタフェース

パラメータの詳細

以下ではパラメータの詳細について説明します。

必須パラメータ

authorization

認証情報

API を利用するためには必ず認証情報を設定する必要があります。認証情報は、マイページに記載された[API キー]、または、API キー発行 APIで取得した API キーです。

注意

ブラウザアプリケーションから音声認識サーバに接続する場合には、認証情報が漏洩してしまった場合の危険性を考慮して、有効期限や IP アドレスの制限付きの API キーを使用することを推奨します。詳細は、API キーを参照してください。

grammarFileNames

接続エンジン名

そのセッションで使用したい音声認識エンジンを指定します。1 回のセッションで 1 つ指定します。設定できる値は接続エンジン名の一覧表か、マイページを参照してください。詳細は音声認識エンジンを参照してください。

オプションパラメータ

profileId

プロファイル ID

プロファイルとは、音声認識サーバ上に存在するユーザーごとのデータファイルで、ユーザーが名前をつけて、登録した単語を保存できます。プロファイル ID はそのデータファイルを指定するための識別子です。詳細は、ユーザー辞書を参照してください。

profileWords

ユーザー辞書単語リスト

セッションで有効なユーザー辞書の単語を登録できます。ハイブリッドエンジンの単語登録の場合、ひとつの単語は『表記<半角スペース>読み』という形式で登録します。クラス名を指定する場合は、『表記<半角スペース>読み<半角スペース>クラス名』としてください。End to End エンジンの単語強調の場合、『表記<半角スペース>代替表記<半角スペース>単語強調度』という形式で登録します。代替表記と単語強調度は省略可能ですが、代替表記のみを省略する場合は『表記<半角スペース><半角スペース>単語強調度』とします。単語登録も単語強調も、複数登録する場合は、単語と単語を「|」(半角縦棒)で区切ります。値のフォーマットは以下のようになります (単語登録でクラス名を指定していない場合の例です)。

表記1 読み1|表記2 読み2|表記3 読み3|表記4 読み4

詳細は、ユーザー辞書を参照してください。

keepFillerToken

フィラー単語（不要語）の自動削除の抑制

1か0を指定します。デフォルトは0です。音声認識結果に含まれるフィラー単語 (「あー」や「えー」など)を自動的に除去したくないときに1を指定します。フィラー単語の自動削除も参照してください。

フィラー単語は単語の前後を半角の「%」で囲まれています。以下はフィラー単語の例です。

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

ヒント

AmiVoice Tech BlogのAmiVoice APIで不要語（フィラー）を表示するか除去するか選ぶ方法も参照してください。

segmenterProperties

発話区間検出のパラメータ

発話の検出されやすさ等を調節するパラメータです。まずはデフォルトで試してみてから、必要に応じて調節を行うようにしてください。パラメータは以下のものを設定できます。

デフォルト値は同期 HTTP インタフェースおよび WebSocket インタフェースが共通で、非同期 HTTP インタフェースは一部異なる値が設定されています。後者は（）内に記載します。

注意

デフォルト値については予告なく変更される可能性があります。

• threshold
  • 発話か否かを判断するためスコアの閾値であり、スコアがこの値以上であれば発話とみなされます。この値を小さくすると発話が検出されやすくなり、発話が途切れたり末尾が切れたりしにくくなりますが、誤検出も起きやすくなります。ノイズが多い環境で誤検出が目立つ場合は、この値を大きくします。
  • デフォルトは 5000（8000）です。
• preTime
  • 発話とみなされた時間が一定時間続いたら、発話区間を検出する状態に移行しますが、この「一定時間」の長さを指定する値です。短い発話が検出されない場合や発話の先頭が切れやすい場合などは、この値を小さくします。短いノイズの誤検出が多い場合は、この値を大きくします。
  • 単位はミリ秒、デフォルトは 100（100）です。50 の倍数で指定してください。
• postTime
  • 発話区間の末尾に非発話とみなされた時間が一定時間続いたら、発話区間を検出する状態を終了しますが、この「一定時間」の長さを指定する値です。発話の途中で区切られてしまう場合は、この値を大きくします。２つの発話がつながってしまう場合は、この値を小さくします。
  • 単位はミリ秒、デフォルトは 550（800）です。
• preForcedTime
  • 発話区間を検出する状態に移行した際に、発話とみなされた最初の時刻からどれだけ遡って発話区間開始地点とするかを指定する値です。発話の先頭が切れやすい場合、この値を大きくします。
  • 単位はミリ秒、デフォルトは 350（350）です。
• postForcedTime
  • 発話区間を検出する状態が終了した際に、非発話とみなされた最終時刻からどれだけ経過した時刻までを発話区間とするかを指定する値です。発話の末尾が切れやすい場合、この値を大きくします。レスポンスのリアルタイム性が悪い場合は、この値を小さくします。
  • 単位はミリ秒、デフォルトは 350（350）です。
• powerThreshold
  • 発話か否かを判断する際に、音量（パワー）も加味する場合のスコアの閾値です。thresholdとは別に設定する必要があり、0 以下の値にすると無効になります。閾値以下のスコアとなった場合は、非発話とみなされます。背景の小さい音を検出しやすい場合、この値を大きくします。
  • デフォルトは 100（100）です。
• decayTime
  • 一定時間が経過したらpostTimeの値を単調減少させて発話を切れやすくすることができ、この「一定時間」を指定する値です。検出される発話区間が長すぎる場合、この値を小さくします。
  • 単位はミリ秒、デフォルトは 5000（15000）です。

上記のパラメータの、利用シーンごとの推奨値は以下のとおりです。

パラメータ	多くの場面に適用できる推奨値（同期 HTTP、WebSocket インタフェースのデフォルト値）	声がとても小さい場面の推奨値	BGM や保留音、非定常ノイズなどが多い場面の推奨値
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

話者ダイアライゼーションに関するパラメータ

話者ダイアライゼーションに関するパラメータです。同期 HTTP と WebSocket インタフェースでのみ設定可能です。以下のパラメータを設定できます。

• useDiarizer
  • 1を設定すると、同期 HTTP や WebSocket インターフェースで話者ダイアライゼーションを有効にします。デフォルトは無効です。詳細は、話者ダイアライゼーションを参照してください。
• diarizerAlpha
  • 同期 HTTP や WebSocket インターフェースでの話者ダイアライゼーションの新規話者の出現しやすさを制御するパラメータです。大きな値を指定するほど新規話者が出現しやすくなり、小さな値を指定するほど新規話者が出現しづらくなります。diarizerAlpha=0は特別で、1e-30 が指定されたものとして扱われます。ただし、8kHz 音声に対応しているエンジン、例えば、汎用エンジン(-a-general)を利用しサンプリングレートが 8kHz の音声を送信した場合は、1e-10 が指定されたものとして扱われます。何も設定しないとdiarizerAlpha=0が指定されたことになります。
• diarizerTransitionBias
  • 同期 HTTP や WebSocket インターフェースでの話者ダイアライゼーションの話者の切り替わりやすさを制御するパラメータです。大きな値を指定するほど話者が切り替わりやすくなり、小さな値を指定するほど話者が切り替わりづらくなります。diarizerTransitionBias=0は特別で、1e-20 が指定されたものとして扱われます。何も設定しないとdiarizerTransitionBias=0が指定されたことになります。

パラメータの設定方法

segmenterProperties=に続けてパラメータの設定を記述してください。複数のパラメータを同時に設定する場合は、それぞれのパラメータは半角スペースで区切ります。

curl コマンドを使用した同期 HTTP インタフェースの設定例

複数パラメータを設定する場合に挿入する半角スペースを%20にURLエンコードします。

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

WebSocket インタフェースの設定例

segmenterPropertiesに設定したパラメータ全体を"..."のようにダブルクォートで囲みます。

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

extension

使用量集計タグ

同一の AmiVoice API アカウントを複数のシステムや環境、エンドユーザ等で共用する場合に、任意の属性ごとの使用量を取得するための集計タグを設定できます。詳細は使用量集計タグを参照してください。

maxDecodingTime

最大認識処理時間

$$\text{これまでにかかった認識処理時間} > \text{maxDecodingTime}$$

となった場合に、音声認識処理を強制的に中断させる機能。単位はミリ秒。

デフォルトでは 0 であり、0 の場合は、この機能は無効です。

maxResponseTime

最大応答時間

$$\text{これまでにかかった認識処理時間} > \text{入力された音声の時間} + \text{maxResponseTime}$$

となった場合に、音声認識処理を強制的に中断させる機能。単位はミリ秒。この機能は、全ての音声データを受信し終わった後にしか発動しない点に注意してください。

デフォルトでは 0 であり、0 の場合は、この機能は無効です。

maxDecodingRate

最大 RT

$$\text{これまでにかかった認識処理時間} > \text{入力された音声の時間} \times \text{maxDecodingRate}$$

となった場合に、音声認識処理を強制的に中断させる機能。この機能は、全ての音声データを受信し終わった後にしか発動しない点に注意してください。

デフォルトでは -1 であり、負の値の場合は、この機能は無効です。

なお、RT とは、音声認識の処理速度を表す数値で、RT = 認識処理にかかった時間 / 入力された音声の時間により計算されるものです。

targetResponseTime

目標応答時間

$\text{暫定 RT} = \frac{\text{これまでにかかった認識処理時間}}{\text{これまでに入力された音声の時間}}$ として「暫定 RT」を計算し、

$$\text{暫定RT} \approx \frac{\text{これまでに入力された音声の時間} + \text{targetResponseTime}}{\text{これまでに入力された音声の時間}}$$

となるように、音声認識処理中に、音声認識の処理速度と認識率のバランスを動的に調節する機能。単位はミリ秒。「これまでに入力された音声の時間」が１秒に満たない場合や、「これまでにかかった認識処理時間」が「これまでに入力された音声の時間」を下回っている(すなわち、「暫定 RT」が１以上になっていない)場合は、この機能は発動しません。

デフォルトでは 0 であり、0 の場合は、この機能は無効です。

targetDecodingRate

目標 RT

$\text{暫定 RT} = \frac{\text{これまでにかかった認識処理時間}}{\text{これまでに入力された音声の時間}}$ として「暫定 RT」を計算し、

$$\text{暫定RT} \approx \text{targetDecodingRate}$$

となるように、音声認識処理中に、音声認識の処理速度と認識率のバランスを動的に調節する機能。「これまでに入力された音声の時間」が１秒に満たない場合や、「これまでにかかった認識処理時間」が「これまでに入力された音声の時間」を下回っている(すなわち、「暫定 RT」が１以上になっていない)場合は、この機能は発動しません。

デフォルトでは -1 であり、負の値の場合は、この機能は無効です。

recognitionTimeout

認識完了タイムアウト

音声認識処理が一定時間内（＝recognitionTimeout）に終わらない場合に、処理を強制的に中断させ、その時点での音声認識の途中結果を得られるようにする機能。単位はミリ秒。この機能が有効な場合、１つの発話区間において音声認識が成功したら、recognitionTimeoutで設定した時間内であっても、以降の発話区間での認識処理は行われません。ただし、音声認識処理の結果、その発話区間の全てがフィラーと認識されてリジェクトされるなど認識結果が得られなかった場合は、引き続き次の発話区間の認識処理が行われます。

同期 HTTP インタフェースおよび非同期 HTTP インタフェースでは、サーバがクライアントからの音声の受信を開始した時点から、WebSocket インタフェースでは、最初の発話区間の先頭が検出された時点から、recognitionTimeoutのカウントが開始されます。なお、recognitionTimeoutの時間の長さは認識処理にかかる時間であり、音声データの時間とは異なります。

デフォルトでは 0 であり、0 の場合は、この機能は無効です。

たとえば一問一答形式のボイスボットのように、有効な認識結果が含まれる発話区間を少しでも早く見つけることが重要であり、それ以降の発話区間に対して認識処理は行わなくて良いような場合に有効な機能です。この機能を有効にしている際に、発話の途中で発話区間が途切れてしまって必要な認識結果が得られないような場合は、segmenterPropertiesのpostTimeを調節してください。

ヒント

recognitionTimeoutとnoInputTimeoutについて、テックブログ『AmiVoice API アップデート解説　ボイスボット向け新パラメータで応答待ち時間を短縮』で詳細な挙動や具体的な使い方を解説しているので、こちらも参考にしてください。

WebSocket API 固有のパラメータ

resultUpdatedInterval

認識中イベントの間隔

認識中イベントを発行する間隔をミリ秒単位で指定します。

• 0 に設定すると認識中イベントを発行しません。
• 指定された時間が経過する毎に認識中イベントを発行します。指定された時間が経過する間に音声認識の処理途中の結果が更新されなかった場合は、直前の認識途中結果の末尾に「.」を一つ追加したものが送られます。100 未満の端数を含む値が指定された場合は、100 の倍数に切り上げた値が指定されたものとして扱います。

noInputTimeout

発話開始待ちタイムアウト

発話区間が一定時間（＝noInputTimeout）検出されなかった場合に、音声認識セッションを強制的に終了し、以降の認識処理を全てキャンセルする機能。単位はミリ秒。この時間の長さは音声認識処理にかかる時間であり、音声データの時間とは異なります。

セッションが終了された場合、クライアントに「e timeout occurred」のエラーが送られます。

デフォルトでは 0 であり、0 の場合は、この機能は無効です。

ヒント

recognitionTimeoutとnoInputTimeoutについて、テックブログ『AmiVoice API アップデート解説　ボイスボット向け新パラメータで応答待ち時間を短縮』で詳細な挙動や具体的な使い方を解説しているので、こちらも参考にしてください。

非同期 HTTP インタフェース 固有のパラメータ

loggingOptOut

ログ保存のあり、なしの変更

loggingOptOut=<True|False> ログの保存のあり、なしを指定します。True に設定するとセッション中、システムはログを保存しません。デフォルトは False です。

contentId

ユーザー定義 ID

contentId=<任意の文字列> ユーザー側で定義した任意の文字列を指定できます。そのセッション中の状態、結果のレスポンスに含まれます。デフォルトは None です。

compatibleWithSync

結果フォーマットの互換性

compatibleWithSync=<True|False> 同期 HTTP インタフェース と互換性のある形で結果をフォーマットします。デフォルトは False です。

speakerDiarization

話者ダイアライゼーションの有効化オプション

speakerDiarization=<True|False> 話者ダイアライゼーションを有効にします。デフォルトは False です。詳細は、話者ダイアライゼーションを参照してください。

diarizationMinSpeaker

話者ダイアライゼーションの最小推定話者人数

diarizationMinSpeaker=<int> 話者ダイアライゼーションが有効になっているときのみ有効で、音声に含まれる最小話者数を指定できます。1 以上に設定する必要があります。デフォルトは 1 です。詳細は、話者ダイアライゼーションを参照してください。

diarizationMaxSpeaker

話者ダイアライゼーションの最大推定話者人数

diarizationMaxSpeaker=<int> 話者ダイアライゼーションが有効になっているときのみ有効で、音声に含まれる最大話者数を指定できます。diarizationMinSpeaker 以上に設定する必要があります。デフォルトは 10 です。詳細は、話者ダイアライゼーションを参照してください。

sentimentAnalysis

感情分析の有効化オプション

sentimentAnalysis=<True|False> 感情分析を有効にします。デフォルトは False です。

詳細は、感情分析を参照してください。