リクエストパラメータ
AmiVoice API で音声認識をリクエストするときに設定するパラメータについて説明します。HTTP、WebSocket インタフェースでそれぞれ送信方法が異なりますが、設定できるパラメータは同じです。
必須パラメータ
以下のパラメータは必ず送信する必要があります。
対応している音声データのフォーマットは、音声フォーマットを参照してください。
オプションパラメータ
音声認識サーバを制御するために以下のパラメータを必要に応じて設定できます。
- 単語登録に関する設定
- 結果テキストを制御するための設定
- 発話区間検出プログラムのパラメータ
WebSocket API 固有のパラメータ
WebSocket インタフェース にのみ設定できるパラメータがあります。
- 結果取得タイミングに関する設定
非同期 HTTP インタフェース 固有のパラメータ
非同期 HTTP インタフェース にのみ設定できるパラメータがあります。
- 一般的な設定
- 話者ダイアライゼーションに関する設定
- 感情分析に関する設定
これらのリクエストパラメータの送信方法については、次のセクションを参照してください。
以下ではパラメータの詳細について説明します。
パラメータの詳細
必須パラメータ
認証情報 (authorization)
API を利用するためには必ず認証情報を設定する必要があります。認証情報は、マイページに記載された[APPKEY]、または、ワンタイム APPKEY 発行 APIで取得したワンタイム APPKEY です。
ブラウザアプリケーションから音声認識サーバに接続する場合には、HTML ファイルに APPKEY を書き込むことを避けるために、ワンタイム APPKEY を使用するようにしてください。詳細は、ワンタイムAPPKEYを参照してください。
接続エンジン名 (grammarFileNames)
そのセッションで使用したい音声認識エンジンを指定します。1 回のセッションで 1 つ指定します。設定できる値は接続エンジン名の一覧表か、マイページを参照してください。詳細は音声認識エンジンを参照してください。
オプションパラメータ
プロファイル ID (profileId)
プロファイルとは、音声認識サーバ上に存在するユーザーごとのデータファイルで、ユーザが名前をつけて、登録した単語を保存できます。プロファイル ID はそのデータファイルを指定するための識別子です。詳細は、単語登録やプロファイルと単語登録についてを参照してください。
単語登録リスト (profileWords)
セッションで有効な単語を登録できます。ひとつの単語は『表記 (半角スペース)読み』という形式で登録します。クラス名を指定する場合は、『表記<半角スペース>読み <半角スペース> クラス名』としてください。複数登録する場合は、単語と単語を「|」(半角縦棒)で区切ります。値のフォーマットは以下のようになります (クラス名を指定していない場合の例です)。
表記1 読み1|表記2 読み2|表記3 読み3|表記4 読み4
詳細は、単語登録やプロファイルと単語登録についてを参照してください。
フィラー単語の出力指定 (keepFillerToken)
発話に含まれるフィラー単語 (「あー」や「えー」など)を自動的に除去したくないときに指定します。フィラー単語の前後は半角の「%」で囲まれています。
例) %あー% %えー% %おー% %えーっと%
keepFillerToken=1
の指定をしていない場合、フィラー単語は認識結果から除去されています。
AmiVoice Tech BlogのAmiVoice APIで不要語(フィラー)を表示するか除去するか選ぶ方法も参照してください。
発話区間検出のパラメータ (segmenterProperties)
以下のパラメータを設定できます。
useDiarizer
1
を設定すると、同期 HTTP や WebSocket インターフェースで話者ダイアライゼーションを有効にします。デフォルトは無効です。詳細は、話者ダイアライゼーションを参照してください。
diarizerAlpha
- 同期 HTTP や WebSocket インターフェースでの話者ダイアライゼーションの新規話者の出現しやすさを制御するパラメータです。大きな値を指定するほど新規話者が出現しやすくなり、小さな値を指定するほど新規話者が出現しづらくなります。
diarizerAlpha=0
は特別で、1e0、つまり 1 が指定されたものとして扱われます。何も設定しないとdiarizerAlpha=0
が指定されたことになります。
- 同期 HTTP や WebSocket インターフェースでの話者ダイアライゼーションの新規話者の出現しやすさを制御するパラメータです。大きな値を指定するほど新規話者が出現しやすくなり、小さな値を指定するほど新規話者が出現しづらくなります。
diarizerTransitionBias
- 同期 HTTP や WebSocket インターフェースでの話者ダイアライゼーションの話者の切り替わりやすさを制御するパラメータです。大きな値を指定するほど話者が切り替わりやすくなり、小さな値を指定するほど話者が切り替わりづらくなります。
diarizerTransitionBias=0
は特別で、1e-40 が指定されたものとして扱われます。ただし、8Kz 音声に対応しているエンジン、例えば、汎用エンジン(-a-general
)を利用しサンプリングレートが8kの音声を送信した場合は、1e-20 が指定されたものとして扱われます。何も設定しないとdiarizerTransitionBias=0
が指定されたことになります。
- 同期 HTTP や WebSocket インターフェースでの話者ダイアライゼーションの話者の切り替わりやすさを制御するパラメータです。大きな値を指定するほど話者が切り替わりやすくなり、小さな値を指定するほど話者が切り替わりづらくなります。
WebSocket API 固有のパラメータ
認識中イベントの間隔 (resultUpdatedInterval)
認識中イベントを発行する間隔をミリ秒単位で指定します。
- 0 に設定すると認識中イベントを発行しません。
- 指定された時間の音声データを認識処理する毎に認識中イベントを発行します。認識中イベントは、実際に経過した時間に応じて発行されるのではなく、認識処理された音声データの処理量に応じて発行されます。100 未満の端数を含む値が指定された場合は、100 の倍数に切り上げた値が指定されたものとして扱います。
非同期 HTTP インタフェース 固有のパラメータ
ログ保存のあり、なしの変更 (loggingOptOut)
loggingOptOut=<True|False>
ログの保存のあり、なしを指定します。True に設定するとセッション中、システムはログを保存しません。デフォルトは False です。
ユーザ定義 ID (contentId)
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 です。
詳細は、感情分析を参照してください。