同期 HTTP インタフェース
同期 HTTP インタフェース は短い音声ファイルを簡単にテキスト化できる Web API です。
エンドポイント
音声認識をリクエストするエンドポイントです。ログ保存あり・なしで、エンドポイントが異なります。詳細は、ログ保存を参照してください。
POST https://acp-api.amivoice.com/v1/recognize （ログ保存あり）
POST https://acp-api.amivoice.com/v1/nolog/recognize （ログ保存なし）
リクエスト
リクエストパラメータ一覧
パラメータ名 | 必須 | 説明 |
|---|---|---|
| u | ● | マイページに表示されているAPPKEY、もしくは、ワンタイム APPKEY を指定します。 |
| d | ● | 音声認識のリクエストに関する様々なパラメータを設定します。dパラメータを参照してください。 |
| a | ● | 音声のバイナリデータを設定します。このデータは必ず HTTP マルチパートの最終パートにする必要があります。送信可能な音声データについては、利用ガイドの音声フォーマットを参照して下さい。 |
| c | RAW データ（PCM）を送信する場合のフォーマット名です。設定できる値は音声フォーマットを参照してください。 |
- 音声データ以外はクエリパラメータでもマルチパートでも送信することができます。クエリパラメータにdパラメータを設定するとリクエストラインの上限を超える可能性があるため、マルチパートで送信することを推奨します。
- クエリパラメータとマルチパートの両方に同じパラメータが指定されている場合、クエリパラメータに設定した値が優先されます。
ｄパラメータ
dパラメータの中は、key-value 形式のパラメータを、半角スペース区切りで指定します。dパラメータの形式は以下の通りです。
例:
<キー>=<値> <キー>=<値> <キー>=<値> ...
スペースが含まれる<値>は URL エンコードしてください。以下の例では、grammarFileNamesとprofileWordsの2つのパラメータを指定しています。profileWordsには表記が "www"、読みが、"とりぷるだぶる"という単語をセットしています。
grammarFileNames=-a-general profileWords=www%20%E3%81%A8%E3%82%8A%E3%81%B7%E3%82%8B%E3%81%A0%E3%81%B6%E3%82%8B
dパラメータに指定できるのは以下の通りです。接続エンジン名（grammarFileNames）は必須です。
| パラメータ名 | 値 | 説明 |
|---|---|---|
| grammarFileNames | {接続エンジン名} | 接続エンジン名の指定。使用可能な接続エンジン名の一覧は、マイページに表示されています。音声認識エンジンの一覧も参照してください。 |
| profileId | 文字列 | 登録単語を指定するためのID。詳細は単語登録を参照してください。 |
| profileWords | 文字列 | セッション中だけで有効にしたい単語登録のリスト。{表記} {読み}もしくは{表記} {読み} {クラス名}のように指定します。複数単語を指定する場合は|で連結します。詳細は単語登録を参照してください。 |
| keepFillerToken | 0|1 | フィラー単語の出力指定。1にするとフィラーを削除しません。デフォルトは0でフィラー単語は認識結果から自動的に除去されます。フィラー単語の出力指定を参照してください。 |
- profileId には、半角英数文字、および、「-」(半角マイナス)、「_」(半角アンダーライン) で構成される文字列が利用できます。ただ し、「__」(半角アンダーライン 2 文字)ではじまる文字列は、 音声認識エンジン側で予約されていますので、「__」(半角アンダーライン 2 文字)ではじまる文字列は指定しないようにしてください。
profileIdとprofileWordsの両方を指定する場合には、profileId を先に指定する必要があります。
レスポンス
レスポンスの構造
<result>には、以下の JSON が格納されています。
| 説明 | |||
|---|---|---|---|
| results | 「発話区間の認識結果」の配列 ※配列形式ですが要素数は常に 1 個です。 | ||
| confidence | 信頼度(0 ～ 1 の値。 0:信頼度低, 1:信頼度高) | ||
| starttime | 発話開始時間 （音声データの先頭が 0） | ||
| endtime | 発話終了時間 （音声データの先頭が 0） | ||
| tags | 未使用（空配列） | ||
| rulename | 未使用（空文字） | ||
| text | 認識結果テキスト | ||
| tokens | 認識結果テキストの形態素の配列 | ||
| written | 形態素（単語）の表記 | ||
| confidence | 形態素の信頼度（認識結果の尤 度） | ||
| starttime | 形態素の開始時間 （音声データの先頭が 0） | ||
| endtime | 形態素の終了時間（音声データの先頭が 0） | ||
| spoken | 形態素の読み *3 | ||
| utteranceid | 認識結果情報 ID *1 | ||
| text | 「発話区間の認識結果」の全てを結合した全体の認識結果テキスト | ||
| code | 結果を表す 1 文字のコード *2 | ||
| message | エラー内容を表す文字列 *2 |
*1 認識結果情報 ID は、WebSocket 音声認識プロトコルの場合は、発話区間毎の認識結果情報に付与された ID となります。HTTP 音声認識プロトコルの場合は、1 セッションでアップロードされた（複数の発話区間を含む可能性のある）音声データ全体の認識結果情報に付与された ID となります。
*2 認識成功時は body.code == "" かつ body.message == "" かつ body.text != "" 認識失敗時は body.code != "" かつ body.message != "" かつ body.text == ""
*3 日本語エンジンの認識結果の spoken は平仮名です。 英語エンジンの認識結果の spoken は読みではありません（無視してください）。 中国語エンジンの認識結果の spoken はピンイン（pinyin）です。
code と message の一覧
<result>に含まれるcodeとmessageに値が設定されているとリクエストに 失敗したことがわかります。失敗の原因は以下のとおりです。
| code | message | 説明 |
|---|---|---|
| + | received unsupported audio format | サポート対象外の音声データ形式の音声データを受信 |
| - | received illegal service authorization | 不正なAPPKEY（サービス認証キー文字列）を受信 |
| ! | failed to connect to recognizer server | 音声認識サーバ内での通信に失敗（音声認識サーバまたはロードバランサーサーバへの接続に失敗） |
| > | failed to send audio data to recognizer server | 音声認識サーバ内での通信に失敗（音声認識サーバへの音声データの送信に失敗） |
| < | failed to receive recognition result from recognizer server | 音声認識サーバ内での通信に失敗（音声認識サーバからの認識結果の受信に失敗） |
| # | received invalid recognition result from recognizer server | 音声認識サーバ内での通信に失敗（音声認識サーバから受信した認識結果の形式が不正） |
| $ | timeout occurred while receiving audio data from client | クライアントからの音声データ受信中に無通信タイムアウトが発生した |
| % | received too large audio data from client | クライアントから受信した音声データバイト数が大きすぎる（WebSocket インタフ ェース では発生しない） |
| o | recognition result is rejected because confidence is below the threshold | 認識結果全体の信頼度が信頼度しきい値を下回ったために認識に失敗 ※ 受け取った音声データ全体から発話が 1 個も検出できなかったため認識結果を返却できない場合にも、このエラーが返却されます。発話検出に失敗する原因としては、音声データの欠損や音声データフォーマットの指定間違いが考えられます。 |
| b | recognition result is rejected because recognizer server is busy | 音声認識サーバが混んでいるために認識に失敗 |
| x | recognition result is rejected because grammar files are not loaded | 辞書が読み込まれていないために認識に失敗 |
| c | recognition result is rejected because the recognition process is cancelled | 認識処理中断要求がなされたために認識に失敗 |
| ? | recognition result is rejected because fatal error occurred in recognizer server | 音声認識サーバで認識中に致命的エラーが発生したために認識に失敗 |
| ^ | invalid parameter (...) | 不正なパラメータが指定されました。非同期HTTPインタフェースのときのみ。 |