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

同期 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" に変換されています。

結果​

実行に成功すると、以下のように JSON 形式の結果が得られます。

{"results":[{"tokens":[{"written":"\u30a2\u30c9\u30d0\u30f3\u30b9\u30c8\u30fb\u30e1\u30c7\u30a3\u30a2","confidence":1.00,"starttime":522,"endtime":1578,"spoken":"\u3042\u3069\u3070\u3093\u3059\u3068\u3081\u3067\u3043\u3042"},{"written":"\u306f","confidence":1.00,"starttime":1578,"endtime":1866,"spoken":"\u306f"},{"written":"\u3001","confidence":0.72,"starttime":1866,"endtime":2026,"spoken":"_"},{"written":"\u4eba","confidence":1.00,"starttime":2026,"endtime":2314,"spoken":"\u3072\u3068"},{"written":"\u3068","confidence":1.00,"starttime":2314,"endtime":2426,"spoken":"\u3068"},{"written":"\u6a5f\u68b0","confidence":1.00,"starttime":2426,"endtime":2826,"spoken":"\u304d\u304b\u3044"},{"written":"\u3068","confidence":1.00,"starttime":2826,"endtime":2938,"spoken":"\u3068"},{"written":"\u306e","confidence":1.00,"starttime":2938,"endtime":3082,"spoken":"\u306e"},{"written":"\u81ea\u7136","confidence":1.00,"starttime":3082,"endtime":3434,"spoken":"\u3057\u305c\u3093"},{"written":"\u306a","confidence":1.00,"starttime":3434,"endtime":3530,"spoken":"\u306a"},{"written":"\u30b3\u30df\u30e5\u30cb\u30b1\u30fc\u30b7\u30e7\u30f3","confidence":1.00,"starttime":3530,"endtime":4378,"spoken":"\u3053\u307f\u3085\u306b\u3051\u30fc\u3057\u3087\u3093"},{"written":"\u3092","confidence":1.00,"starttime":4378,"endtime":4442,"spoken":"\u3092"},{"written":"\u5b9f\u73fe","confidence":1.00,"starttime":4442,"endtime":4922,"spoken":"\u3058\u3064\u3052\u3093"},{"written":"\u3057","confidence":1.00,"starttime":4922,"endtime":5434,"spoken":"\u3057"},{"written":"\u3001","confidence":0.45,"starttime":5434,"endtime":5562,"spoken":"_"},{"written":"\u8c4a\u304b","confidence":1.00,"starttime":5562,"endtime":5994,"spoken":"\u3086\u305f\u304b"},{"written":"\u306a","confidence":1.00,"starttime":5994,"endtime":6090,"spoken":"\u306a"},{"written":"\u672a\u6765","confidence":1.00,"starttime":6090,"endtime":6490,"spoken":"\u307f\u3089\u3044"},{"written":"\u3092","confidence":1.00,"starttime":6490,"endtime":6554,"spoken":"\u3092"},{"written":"\u5275\u9020","confidence":0.93,"starttime":6554,"endtime":7050,"spoken":"\u305d\u3046\u305e\u3046"},{"written":"\u3057\u3066","confidence":0.99,"starttime":7050,"endtime":7210,"spoken":"\u3057\u3066"},{"written":"\u3044\u304f","confidence":1.00,"starttime":7210,"endtime":7418,"spoken":"\u3044\u304f"},{"written":"\u3053\u3068","confidence":1.00,"starttime":7418,"endtime":7690,"spoken":"\u3053\u3068"},{"written":"\u3092","confidence":1.00,"starttime":7690,"endtime":7722,"spoken":"\u3092"},{"written":"\u76ee\u6307\u3057","confidence":0.76,"starttime":7722,"endtime":8090,"spoken":"\u3081\u3056\u3057"},{"written":"\u307e\u3059","confidence":0.76,"starttime":8090,"endtime":8506,"spoken":"\u307e\u3059"},{"written":"\u3002","confidence":0.82,"starttime":8506,"endtime":8794,"spoken":"_"}],"confidence":0.998,"starttime":250,"endtime":8794,"tags":[],"rulename":"","text":"\u30a2\u30c9\u30d0\u30f3\u30b9\u30c8\u30fb\u30e1\u30c7\u30a3\u30a2\u306f\u3001\u4eba\u3068\u6a5f\u68b0\u3068\u306e\u81ea\u7136\u306a\u30b3\u30df\u30e5\u30cb\u30b1\u30fc\u30b7\u30e7\u30f3\u3092\u5b9f\u73fe\u3057\u3001\u8c4a\u304b\u306a\u672a\u6765\u3092\u5275\u9020\u3057\u3066\u3044\u304f\u3053\u3068\u3092\u76ee\u6307\u3057\u307e\u3059\u3002"}],"utteranceid":"20220602/14/018122d637320a301bc194c9_20220602_141433","text":"\u30a2\u30c9\u30d0\u30f3\u30b9\u30c8\u30fb\u30e1\u30c7\u30a3\u30a2\u306f\u3001\u4eba\u3068\u6a5f\u68b0\u3068\u306e\u81ea\u7136\u306a\u30b3\u30df\u30e5\u30cb\u30b1\u30fc\u30b7\u30e7\u30f3\u3092\u5b9f\u73fe\u3057\u3001\u8c4a\u304b\u306a\u672a\u6765\u3092\u5275\u9020\u3057\u3066\u3044\u304f\u3053\u3068\u3092\u76ee\u6307\u3057\u307e\u3059\u3002","code":"","message":""}

認識結果に含まれる日本語は UTF-8 を Unicode エスケープした形式です。お使いの開発言語に備わる JSON パーサーなどで、簡単に元にもどせます。ここでは jq コマンドを使って変換します。

curl -F a=@test.wav "https://acp-api.amivoice.com/v1/recognize?d=-a-general&u=<APPKEY>" | jq

今度は、認識結果の日本語が読めるような形式で、かつ、インデントつきで表示されるはずです。結果に含まれるtextを探してください。ここに音声を書き起こした結果があります。

"text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。"

以下はレスポンスの完全な例です。文字起こしした結果だけではなく、単語単位の結果や音声時間、信頼度などの情報も得られます。詳細は、音声認識の結果を参照してください。

レスポンス
{
  "results": [
    {
      "tokens": [
        {
          "written": "アドバンスト・メディア",
          "confidence": 1,
          "starttime": 522,
          "endtime": 1578,
          "spoken": "あどばんすとめでぃあ"
        },
        {
          "written": "は",
          "confidence": 1,
          "starttime": 1578,
          "endtime": 1866,
          "spoken": "は"
        },
        {
          "written": "、",
          "confidence": 0.72,
          "starttime": 1866,
          "endtime": 2026,
          "spoken": "_"
        },
        {
          "written": "人",
          "confidence": 1,
          "starttime": 2026,
          "endtime": 2314,
          "spoken": "ひと"
        },
        {
          "written": "と",
          "confidence": 1,
          "starttime": 2314,
          "endtime": 2426,
          "spoken": "と"
        },
        {
          "written": "機械",
          "confidence": 1,
          "starttime": 2426,
          "endtime": 2826,
          "spoken": "きかい"
        },
        {
          "written": "と",
          "confidence": 1,
          "starttime": 2826,
          "endtime": 2938,
          "spoken": "と"
        },
        {
          "written": "の",
          "confidence": 1,
          "starttime": 2938,
          "endtime": 3082,
          "spoken": "の"
        },
        {
          "written": "自然",
          "confidence": 1,
          "starttime": 3082,
          "endtime": 3434,
          "spoken": "しぜん"
        },
        {
          "written": "な",
          "confidence": 1,
          "starttime": 3434,
          "endtime": 3530,
          "spoken": "な"
        },
        {
          "written": "コミュニケーション",
          "confidence": 1,
          "starttime": 3530,
          "endtime": 4378,
          "spoken": "こみゅにけーしょん"
        },
        {
          "written": "を",
          "confidence": 1,
          "starttime": 4378,
          "endtime": 4442,
          "spoken": "を"
        },
        {
          "written": "実現",
          "confidence": 1,
          "starttime": 4442,
          "endtime": 4922,
          "spoken": "じつげん"
        },
        {
          "written": "し",
          "confidence": 1,
          "starttime": 4922,
          "endtime": 5434,
          "spoken": "し"
        },
        {
          "written": "、",
          "confidence": 0.45,
          "starttime": 5434,
          "endtime": 5562,
          "spoken": "_"
        },
        {
          "written": "豊か",
          "confidence": 1,
          "starttime": 5562,
          "endtime": 5994,
          "spoken": "ゆたか"
        },
        {
          "written": "な",
          "confidence": 1,
          "starttime": 5994,
          "endtime": 6090,
          "spoken": "な"
        },
        {
          "written": "未来",
          "confidence": 1,
          "starttime": 6090,
          "endtime": 6490,
          "spoken": "みらい"
        },
        {
          "written": "を",
          "confidence": 1,
          "starttime": 6490,
          "endtime": 6554,
          "spoken": "を"
        },
        {
          "written": "創造",
          "confidence": 0.93,
          "starttime": 6554,
          "endtime": 7050,
          "spoken": "そうぞう"
        },
        {
          "written": "して",
          "confidence": 0.99,
          "starttime": 7050,
          "endtime": 7210,
          "spoken": "して"
        },
        {
          "written": "いく",
          "confidence": 1,
          "starttime": 7210,
          "endtime": 7418,
          "spoken": "いく"
        },
        {
          "written": "こと",
          "confidence": 1,
          "starttime": 7418,
          "endtime": 7690,
          "spoken": "こと"
        },
        {
          "written": "を",
          "confidence": 1,
          "starttime": 7690,
          "endtime": 7722,
          "spoken": "を"
        },
        {
          "written": "目指し",
          "confidence": 0.76,
          "starttime": 7722,
          "endtime": 8090,
          "spoken": "めざし"
        },
        {
          "written": "ます",
          "confidence": 0.76,
          "starttime": 8090,
          "endtime": 8506,
          "spoken": "ます"
        },
        {
          "written": "。",
          "confidence": 0.82,
          "starttime": 8506,
          "endtime": 8794,
          "spoken": "_"
        }
      ],
      "confidence": 0.998,
      "starttime": 250,
      "endtime": 8794,
      "tags": [],
      "rulename": "",
      "text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。"
    }
  ],
  "utteranceid": "20220602/14/018122d65d370a30116494c8_20220602_141442",
  "text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。",
  "code": "",
  "message": ""
}

その他のドキュメント​

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