リクエストパラメータ

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

パラメータの一覧

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

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

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

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

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

パラメータの詳細

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

必須パラメータ

authorization

認証情報

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

注意

ブラウザアプリケーションから音声認識サーバに接続する場合には、HTML ファイルに APPKEY を書き込むことを避けるために、ワンタイム APPKEY を使用するようにしてください。詳細は、ワンタイムAPPKEYを参照してください。

grammarFileNames

接続エンジン名

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

オプションパラメータ

profileId

プロファイル ID

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

profileWords

単語登録リスト

セッションで有効な単語を登録できます。ひとつの単語は『表記 (半角スペース)読み』という形式で登録します。クラス名を指定する場合は、『表記<半角スペース>読み <半角スペース> クラス名』としてください。複数登録する場合は、単語と単語を「|」(半角縦棒)で区切ります。値のフォーマットは以下のようになります (クラス名を指定していない場合の例です)。

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

詳細は、単語登録を参照してください。

keepFillerToken

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

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

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

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

ヒント

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

segmenterProperties

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

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

注意

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

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

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

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

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

パラメータの設定方法

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

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

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

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

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

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

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

WebSocket API 固有のパラメータ

resultUpdatedInterval

認識中イベントの間隔

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

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

非同期 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 です。

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