同期 HTTP インタフェース

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

利用の方法

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

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

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

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

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

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

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

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

curl 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--

危険

aパラメータの後に設定されたパラメータは無視されます。

例えば、以下のようにuパラメータを最後にすると認証エラーとなってしまいます。

curl https://acp-api.amivoice.com/v1/nolog/recognize \
     -F d=-a-general \
     -F a=@test.wav \
     -F u={APP_KEY}      # aの後にuを指定している

レスポンス

{
  "results": [
    {
      "tokens": [],
      "tags": [],
      "rulename": "",
      "text": ""
    }
  ],
  "text": "",
  "code": ":"-",
  "message":"received illegal service authorization"
}

また、以下のようにdパラメータを最後にすると指定した音声認識エンジンが見つからないというエラーになります。

curl https://acp-api.amivoice.com/v1/nolog/recognize \
     -F u={APP_KEY} \
     -F a=@test.wav \
     -F d=-a-general      # aの後にdを指定している

レスポンス

{
  "results": [
    {
      "tokens": [],
      "tags": [],
      "rulename": "",
      "text": ""
    }
  ],
  "text": "",
  "code": "!",
  "message": "failed to connect to recognizer server (can't find available servers)"
}

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

音声フォーマットの指定

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

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

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

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

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

マルチパート 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="c"

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

複数パラメータ

プロファイル ID (profileId)など、必須パラメータ以外のリクエストパラメータを設定したい場合は、以下のようにdパラメータに複数のパラメータを設定できます。

d=<キー>=<値> <キー>=<値> <キー>=<値> ...

それぞれの<キー>=<値>は、半角スペース、もしくは、改行で区切ってください。
接続エンジン名は必須ですので、この場合、grammarFileNames=-a-generalのように grammarFileNamesを key として指定してください。

例:

curl 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 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以外のパラメータ、c、d、uは、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 インタフェースクライアント）を参照してください。

利用の方法​

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

音声フォーマットの指定​

複数パラメータ​

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

その他のドキュメント​