メインコンテンツまでスキップ

同期 HTTP インタフェース

同期 HTTP インタフェース は、リクエストパラメータと音声データをサーバに送信すると、レスポンスとして音声認識の結果を受け取ることができます。

利用の方法

音声認識のリクエストの送信

リクエストパラメータの認証情報、接続エンジン名、音声データをそれぞれ、

  • u={認証情報}
  • d={接続エンジン名}
  • a={音声データバイナリ}

のようにパラメータ名を指定してマルチパート POST でサーバに送信します。音声のバイナリデータは必ず HTTP マルチパートの最終パートに置きます。

エンドポイントは、ログ保存のあり・なしによって異なります。

POST https://acp-api.amivoice.com/v1/recognize   (ログ保存あり)
POST https://acp-api.amivoice.com/v1/nolog/recognize (ログ保存なし)

それぞれの違いは、ログ保存を参照してください。

curl コマンドで実際に音声認識のリクエストをしてみます。会話_汎用エンジン(-a-general)を使って、サンプルに同梱している音声ファイル(test.wav)を、音声認識するには以下のようにします。ここでは音声ログはサーバには残さない「ログ保存なし」のエンドポイントに接続しています。

curl -X POST https://acp-api.amivoice.com/v1/nolog/recognize \
-F u={APP_KEY} \
-F d=-a-general \
-F a=@test.wav
注記

マルチパート POST のリクエストの HTTP ヘッダと HTTP ボディは以下のような構造になります。

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"

-a-general
--some-boundary-string
Content-Disposition: form-data; name="a"
Content-Type: application/octet-stream

(最後のパートに音声データを格納します)
--some-boundary-string--

レスポンスについては音声認識の結果を参照してください。

音声フォーマットの指定

送信する音声が、ヘッダのついた音声データ(WAV や Ogg など)ではない場合、音声フォーマットを指定する必要があります。音声フォーマットは、リクエストパラメータcに続けて音声フォーマットを設定します。

  • c={音声フォーマット}

指定できる音声フォーマットは、音声フォーマット対応表を参照してください。

例えば、サンプリングレート16kHz、ビットレート16bit、バイトオーダーがリトルエンディアンの音声ファイルtest.pcmを送信する場合、以下のようにパラメータcLSB16Kを指定します。

curl -X POST https://acp-api.amivoice.com/v1/recognize \
-F u={APP_KEY} \
-F d=-a-general \
-F c=LSB16K \
-F a=@test.pcm
注記

マルチパート POST は以下のような構造になります。

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"

-a-general
--some-boundary-string
Content-Disposition: form-data; name="c"

LSB16K
--some-boundary-string
Content-Disposition: form-data; name="a"
Content-Type: application/octet-stream
(最後のパートに音声データを格納します)
--some-boundary-string--

複数パラメータ

プロファイル ID (profileId)など、他のリクエストパラメータを設定したい場合には、key-value 形式のパラメータを半角スペース、もしくは、改行で区切って複数設定できます。このとき、接続エンジン名はgrammarFileNames=-a-generalのように grammarFileNamesを key として指定します。

<キー>=<> <キー>=<> <キー>=<> ...

例:

curl -X POST https://acp-api.amivoice.com/v1/recognize \
-F u={APP_KEY} \
-F d="grammarFileNames=-a-general profileId=:user01" \
-F a=@test.wav

<値>は、URL エンコードする必要があります。 例えば、profileWordsに表記が "www"、読みが、"とりぷるだぶる"という単語をセットする場合は、表記と読みの間のスペースを%20に、とりぷるだぶるを、%E3%81%A8%E3%82%8A%E3%81%B7%E3%82%8D%E3%81%A0%E3%81%B6%E3%82%8Bのようにエンコードします。

curl -X POST https://acp-api.amivoice.com/v1/recognize \
-F u={APP_KEY} \
-F d="grammarFileNames=-a-general profileWords=hogehoge%20%E3%81%A8%E3%82%8A%E3%81%B7%E3%82%8D%E3%81%A0%E3%81%B6%E3%82%8B" \
-F a=@test.wav
注記
  • 文字コードは UTF-8 にしてください
  • ここでの URL エンコードは、半角スペースが"+"ではなく、"%20"に変換される方式です

パラメータを URL クエリ文字列として送信する場合

a以外のパラメータ、cduは、URL クエリー文字列でも、HTTP ボディにマルチパート方式でも送信できます。

注記
  • HTTP ヘッダのサイズ制限に抵触しないよう、すべてのパラメータをマルチパート方式で送信することを推奨します。
  • URL のクエリー文字列とマルチパートの両方に同じパラメータが指定されている場合、マルチパートに格納された値が優先されます。
  • uはクエリー文字列として送信できますが、通信経路のログなどに残ってしまい漏洩してしまう危険性があるため、必ず HTTP ボディにマルチパート方式で送信してください。

dパラメータをクエリー文字列として送信する場合は、dパラメータの値を再度 URL エンコードする必要があります。

https://acp-api.amivoice.com/v1/recognize?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

"%" は "%25" に、"=" は "%3D" に、半角スペースは "%20" に変換されています。

その他のドキュメント

  • API リファレンスは、同期 HTTP インタフェースを参照してください。
  • HTTP インタフェース を利用する際の通信処理や手順をクラスライブラリ化し、音声認識アプリケーションに必要なインタフェースを実装するだけで簡単に音声認識アプリケーションを作成できるクライアントライブラリ (Hrp)を提供しています。まずはサンプルプログラム HrpTesterを動かしてみてください。Hrp クライアントライブラリのインタフェース仕様については、クライアントライブラリの Hrp(HTTP インタフェース クライアント) を参照してください。