I/F仕様 HTTP音声認識API 詳細
◆リクエスト
リクエストパラメータ
リクエストパラメータは、u、d、a、c、r の5種類があります。必須のもの（u、d、a）と省略可能なもの（c、r）に分かれます。すべてのパラメータはHTTPボディにマルチパート方式で格納して送信することが可能です。aの音声データは、必ず「マルチパートの最終パート」で送信する必要があります。それ以外のパラメータはURLクエリー文字列で送信することも可能ですが、HTTPヘッダのサイズ制限に抵触しないよう、すべてのパラメータをマルチパート方式で送信することを推奨します。
尚、URLのクエリー文字列とマルチパートの両方に同じパラメータが指定されている場合、マルチパートに格納された値が優先されます。
| パラメータ名 | 必須 | クエリー文字列送信 | マルチパート送信 | 説明 |
| u | 必須 | 可 | 可 | マイページに表示されている [APPKEY] もしくは、ワンタイム AppKey発行APIで取得したワンタイム AppKeyを指定します。 ※ブラウザアプリから音声認識サーバに接続する場合には、HTMLファイルに AppKeyを書き込むことを避けるために、ワンタイム AppKeyを使用するようにしてください。詳細は、チュートリアル > ワンタイムAppKeyについてを参照してください。 |
| d | 必須 | 可 | 可 | dパラメータの中は、キーバリュー形式の「子パラメータ」を、半角スペース区切りで複数格納することができます。 <キー>=<値> <キー>=<値> <キー>=<値> … 各<値> は、必ずURLエンコードされている必要があります。これは、マルチパートに格納する場合でも同様です。 従って、より詳細に書けば、以下の形式になります。 <キー>=<URLエンコードされた値> <キー>=<URLエンコードされた値> <キー>=<URLエンコードされた値> … URLエンコードされる前の文字コードはUTF-8であること、半角スペースが”%20″に変換されるエンコード方式であることに留意ください。 「子パラメータ」の種類は以下の通りです。 このうち、必須は接続エンジン名（grammarFileNames）だけになります。 ・接続エンジン名（grammarFileNames） grammarFileNames=<URLエンコードされた接続エンジン名 >このセッションで使用したい「接続エンジン名」（認識エンジン）を指定します。1回のセッションで使用可能な接続エンジン名は、1個です。使用可能な接続エンジン名の一覧は、マイページに表示されています。 ・プロファイルID（profileId） profileId=<URLエンコードされた値>プロファイルとは、音声認識サーバ上に存在するユーザー固有のデータファイルであり、主としてユーザーの登録単語を保存するために利用されます。プロファイルIDはそのデータファイルの識別子です。本サービスでは、ユーザー登録時に、ユーザーIDと一致したプロファイルIDが自動的に各ユーザーに振り出されています。ユーザーが自分の単語登録ページで単語を登録した場合、その単語は、ユーザーIDを識別子とするプロファイル（マイ単語帳）に保存されることになります。「マイ単語帳」を認識処理に活用するためには、「ユーザーIDの先頭に半角コロン”:”を付加した文字列」をURLエンコードして、profileId に指定します。 （例）ユーザ ー IDが「aiueo12345」の場合、「:aiueo12345」をURLエンコードした文字列を値とします。 profileId=%3Aaiueo12345 ※ “%3A”は、半角コロンがURLエンコードされたものです。 ・単語登録リスト(profileWords) profileWords=<URLエンコードされた値>このセッションの認識処理で利用することを目的として、一時的な単語登録をすることができます。ひとつの単語は『表記（半角スペース）読み』という形式で登録します。複数登録する場合は、単語と単語を「|」（半角縦棒）で区切ります。値のフォーマットは以下のようになります。 表記1 読み1|表記2 読み2|表記3 読み3|表記4 読み4※通常は、マイページの単語登録画面で単語登録を行う方が効率的です。単語登録画面での単語登録の仕方はチュートリアル > プロファイルと単語登録についてを参照してください。 ※ profileWordsで一時的な単語登録を行う場合には、profileIdを指定する必要はありません。 ※ profileWordsに沢山の単語を設定してクエリー文字列で送信すると、HTTPヘッダのサイズ制限に抵触する場合があります。それを避けるためにも、dパラメータはマルチパート方式で送信してください。 ※ profileId とprofileWords の両方を指定する場合には、 profileId を先に指定する必要があります。 |
| a | 必須 | 不可 | 可 | 音声のバイナリデータを格納します。このデータは必ずHTTPマルチパートの最終パートに格納する必要があります。送信可能な音声データ形式は、チュートリアル > 音声フォーマットについてを参照して下さい。 |
| c | △ | 可 | 可 | ヘッダのついた音声データ（WAVやOgg）を送信する場合は省略可能です。RAWデータ（PCM）を送信する場合には、このパラメータにフォーマット名を指定する必要があります。フォーマット名については、チュートリアル> 音声フォーマットについてを参照してください。 |
| r | 省略可 | 可 | 可 | 認識結果タイプです。”JSON”を指定します。省略時のデフォルト値も”JSON”になっています。 |
ｄパラメータの値の構造
「dパラメータの値」の構造は以下の通りです。
<key>=<urlencoded value>[ <key>=<urlencoded value>]*
dパラメータをマルチパートPOST送信する場合
リクエストをマルチパートPOSTする場合は、dパートのボディに「dパラメータの値」をそのまま格納すればOKです（”d=”は不要）。
例えば、grammarFileNamesを-a-generalとし、profileWordsにひとつの単語（表記がhogehogeで読みが「ほげほげてすと」）をセットする場合の、「dパラメータの値」は以下のとおりです。「dパラメータの値」には、半角スペースで区切られた2個の<key>=<urlencoded value>が含まれています。
grammarFileNames=-a-general profileWords=hogehoge%20%E3%81%BB%E3%81%92%E3%81%BB%E3%81%92%E3%81%A6%E3%81%99%E3%81%A8
dパラメータをURLクエリ文字列として送信する場合
dパラメータをクエリー文字列（GET）で送る場合には、上の「dパラメータの値」全体が”d=”の右に来るひとつの値となりますので、「dパラメータの値」そのもの（全体）を再度URLエンコードする必要があります。その結果、「dパラメータの値」に含まれる “%” は “%25″ に変換され、”=” は “%3D” に変換され、半角スペースは “%20” に変換されることになります。以下は、実際にクエリー送信する場合の例です。
https://aaa.bbb.ccc?d=grammarFileNames%3D-a-general%20profileWords%3Dhogehoge%2520%25E3%2581%25BB%25E3%2581%2592%25E3%2581%25BB%25E3%2581%2592%25E3%2581%25A6%25E3%2581%2599%25E3%2581%25A8
※ grammarFileNames を省略して、”d=”に続けて接続エンジン名をそのまま記述する書式も可能です。その場合、以下のようになります。
https://aaa.bbb.ccc?d=-a-general%20profileWords%3Dhogehoge%2520%25E3%2581%25BB%25E3%2581%2592%25E3%2581%25BB%25E3%2581%2592%25E3%2581%25A6%25E3%2581%2599%25E3%2581%25A8
マルチパートPOSTのリクエストイメージ
以下のHTTPリクエストのイメージは、マルチパートでPOST送信する場合の、HTTPヘッダとHTTPボディです。この例では、u、d、aの各パラメータの値を格納するために、HTTPボディが3個のパートに分かれています。
POST https://acp-api.amivoice.com/v1/recognize Content-Type: multipart/form-data;boundary=some-boundary-string-- some-boundary-stringsome-boundary-string Content-Disposition: form-data; name="u" （このパートには<AppKey> を格納します） -- some-boundary-string Content-Disposition: form-data; name="d" grammarFileNames=-a-general profileWords=hogehoge%20%E3%81%BB%E3%81%92%E3%81%BB%E3%81%92%E3%81%A6%E3%81%99%E3%81%A8 -- 音声データを Content-Disposition: form-data; name="a" Content-Type: application/octet-stream （最後のパートに some-boundary-string 格納します） -- --
◆レスポンス
返却されるJSON
| キー | キー | キー | 説明 |
| results | 「発話区間の認識結果」の配列 | ||
| confidence | 信頼度(0～1の値。 0:信頼度低, 1:信頼度高) | ||
| starttime | 発話開始時間 （音声データの先頭が0） | ||
| endtime | 発話終了時間 （音声データの先頭が0） | ||
| tags | 未使用（空配列） | ||
| rulename | 未使用（空文字） | ||
| text | 認識結果テキスト | ||
| tokens | 認識結果テキストの形態素の配列 | ||
| written | 形態素（単語）の表記 | ||
| confidence | 形態素の信頼度（認識結果の尤度） | ||
| starttime | 形態素の開始時間 （音声データの先頭が0） | ||
| endtime | 形態素の終了時間（音声データの先頭が0） | ||
| spoken | 形態素の読み | ||
| utteranceid | 認識結果情報ID *1 | ||
| text | 「発話区間の認識結果」の全てを結合した全体の認識結果テキスト | ||
| code | 結果を表す1文字のコード *2 JSONに含まれるcodeとmessage一覧を参照のこと。 | ||
| message | エラー内容を表す文字列 *2 JSONに含まれるcodeとmessage一覧を参照のこと。 |
*1
認識結果情報IDは、WebSocket音声認識プロトコルの場合は、発話区間毎の認識結果情報に付与されたIDとなります。HTTP音声認識プロトコルの場合は、1セッションでアップロードされた（複数の発話区間を含む可能性のある）音声データ全体の認識結果情報に付与されたIDとなります。
*2
認識成功時は
body.code == “” かつ body.message == “” かつ body.text != “”
認識失敗時は
body.code != “” かつ body.message != “” かつ body.text == “”
JSONに含まれるcodeとmessageの一覧
| code | message | 説明 |
| “+” | “received unsupported audio format” | サポート対象外の音声データ形式の音声データを受信 |
| “-“ | “received illegal service authorization” | 不正なサービス認証キー文字列を受信 |
| “!” | “failed to connect to recognizer server” | 音声認識サーバ内での通信に失敗（DSRM または DSRS への接続に失敗） |
| “>” | “failed to send audio data to recognizer server” | 音声認識サーバ内での通信に失敗（DSRS への音声データの送信に失敗） |
| “<“ | “failed to receive recognition result from recognizer server” | 音声認識サーバ内での通信に失敗（DSRS からの認識結果の受信に失敗） |
| “#” | “received invalid recognition result from recognizer server” | 音声認識サーバ内での通信に失敗（DSRS から受信した認識結果の形式が不正） |
| “$” | “timeout occurred while receiving audio data from client” | クライアントからの音声データ受信中に無通信タイムアウトが発生した |
| “%” | “received too large audio data from client” | クライアントから受信した音声データバイト数が大きすぎる（WebSocket音声認識APIでは発生しない） |
| “o” | “recognition result is rejected because confidence is below the threshold” | 認識結果全体の信頼度が信頼度しきい値を下回ったために認識に失敗 |
| “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” | 認識処理中断要求がなされたために認識に失敗 |
| “t” | “recognition result is rejected because timeout occurred during recognition process” | 認識処理がタイムアウトするなどして認識処理が中断されたために認識に失敗 |
| “?” | “recognition result is rejected because fatal error occurred in recognizer server” | 音声認識サーバで認識中に致命的エラーが発生したために認識に失敗 |
| “s” | “recognition result is rejected because recognition process was not started before timeout occurred” | クライアントから受信した音声データが音声データキューに入れられてからある一定時間以内に認識処理が開始しなかったために認識失敗 |
| “e” | “recognition result is rejected because recognition process was not finished before timeout occurred” | クライアントから受信した音声データが音声データキューに入れられてからある一定時間以内に認識処理が完了しなかったために認識失敗 |
| “” | “” | 認識成功 |
◆実行例
cURLコマンドサンプル
curl -i -X POST -H "Content-Type:multipart/form-data" -F a=@audio/test.wav "https://acp-api.amivoice.com/v1/recognize?d=-a-general&u=<AppKey>"
※ 上のcurlコマンドを実行する場合には、ダウンロードしたサンプルプログラムを解凍してできるsampleフォルダ直下をカレントディレクトリとして実行してください。これは、指定したtest.wavがみつかるようにするためです。また、引数の<AppKey>には、マイページに表示されている[APPKEY]を設定してください。
レスポンスサンプル
{"results":[{"tokens":[{"written":"\u30a2\u30c9\u30d0\u30f3\u30b9\u30c8\u30fb\u30e1\u30c7\u30a3\u30a2","confidence":0.93,"starttime":554,"endtime":1562, …
…
"text":"\u30a2\u30c9\u30d0\u30f3\u30b9\u30c8\u30fb\u30e1\u30c7\u30a3\u30a2\u306f …
"code":"","message":""}