I/F仕様 HTTP音声認識API 詳細 - AmiVoice Cloud Platform

◆リクエスト

リクエストパラメータ

リクエストパラメータは、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パラメータの値の構造

「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-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
--some-boundary-string
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の一覧

codemessage説明
“+”“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":""}