同期 HTTP 音声認識 API
同期 HTTP 音声認識 API は短い音声ファイルを簡単にテキスト化できる Web API です。
エンドポイント
音声認識をリクエストするエンドポイントです。ログ保存あり・なしで、エンドポイントが異なります。詳細は、ログ保存を参照してください。
POST https://acp-api.amivoice.com/v1/recognize （ログ保存あり）
POST https://acp-api.amivoice.com/v1/nolog/recognize （ログ保存なし）
リクエスト
リクエストパラメータ
HTTP リクエスメソッドには必ず POST を指定してください。リクエストパラメータは、u、d、a、c、r の 5 種類があります。このうち、u、d、aは必須です。
uパラメータには、AppKey を設定しますdパラメータには、音声認識のリクエストに関する様々なパラメータを設定します。エンジン名の設定は必須です。aパラメータには、書き起こししたい音声データをセットします。aパラメータは必ず「マルチパートの最終パート」で送信する必要があります。
- すべてのパラメータは HTTP ボディにマルチパート方式で格納して送信ですます。それ以外のパラメータは URL クエリー文字列で送信できますが、HTTP ヘッダのサイズ制限に抵触しないよう、すべてのパラメータをマルチパート方式で送信することを推奨します。
- URL のクエリー文字列とマルチパートの両方に同じパラメータが指定されている場合、マルチパートに格納された値が優先されます。
リクエストパラメータ一覧
| パラメータ名 | 必須 | クエリー文字列送信 | マルチパート送信 | 説明 |
|---|---|---|---|---|
| u | 必須 | 可 | 可 | マイページに表示されている [APPKEY] もしくは、ワンタイム AppKey 発行 API で取得したワンタイム AppKey を指定します。 ※ブラウザアプリケーションから音声認識サーバに接続する場合には、HTML ファイルに AppKey を書き込むことを避けるために、ワンタイム AppKey を使用するようにしてください。詳細は、利用ガイドのワンタイム AppKey についてを参照してください。 |
| d | 必須 | 可 | 可 | key-value形式の「子パラメータ」を、半角スペース区切りで設定します。 |
| a | 必須 | 不可 | 可 | 音声のバイナリデータを格納します。このデータは必ず HTTP マルチパートの最終パートに格納する必要があります。送信可能な音声データ形式は、利用ガイドの音声フォーマットについてを参照して下さい。 |
| c | 可 | 可 | ヘッダのついた音声データ（WAV や Ogg）を送信する場合は省略可能です。RAW データ（PCM）を送信する場合には、このパラメータにフォーマット名を指定する必要があります。フォーマット名については、利用ガイドの音声フォーマットについてを参照してください。 | |
| r | 可 | 可 | 認識結果タイプです。"JSON"を指定します。省略時のデフォルト値も"JSON"になっています。 |
ｄパラメータについて
d パラメータの中は、key-value 形式の「子パラメータ」を、半角スペース区切りで複数格納できます。
例:
<キー>=<値> <キー>=<値> <キー>=<値> ...
各<値> は、必ず URL エンコードされている必要があります。これは、マルチパートに格納する場合でも同様です。従って、より詳細に書けば、以下の形式になります。
<キー>=<URL エンコードされた値> <キー>=<URL エンコードされた値> <キー>=<URL エンコードされた値> ...
- URL エンコードされる前の文字コードは UTF-8 にしてください
- 半角スペースが"%20"に変換されるエンコード方式です
「子パラメータ」の種類は以下の通りです。このうち、必須は接続エンジン名（grammarFileNames）だけになります。
接続エンジン名（grammarFileNames）
grammarFileNames=<URLエンコードされた接続エンジン名 >
このセッションで使用したい「接続エンジン名」（認識エンジン）を指定します。1 回のセッションで使用可能な接続エンジン名は、1 個です。使用可能な接続エンジン名の一覧は、マイページに表示されています。
プロファイル ID（profileId）
profileId=<値>
プロファイルとは、音声認識サーバ上に存在するユーザー固有のデータファイルであり、主としてユーザーの登録単語を保存するために利用されます。プロファイル ID はそのデータファイルの識別子です。ユーザーがマイページで単語を登録した場合、その単語は、マイページの接続情報に記載のあるサービス ID（ユーザー ID から自動生成されます）を識別子とするプロファイル（マイ単語帳）に保存されます。「マイ単語帳」を認識処理に活用するためには、「サービス ID の先頭に半角コロン":"を付加した文字列」を、profileId に指定します。
例）サービス ID が「aiueo12345」の場合
profileId=:aiueo12345
grammarFileNamesやprofileWordsのように"値"をURLエンコードしても構いません。:は、URLエンコードすると%3Aになりますので、上記のサンプルは以下のようにしても問題ありません。
profileId=%3Aaiueo12345
profileId には、半角英数文字、および、「-」(半角マイナス)、「_」(半角アンダーライン) で構成される文字列が利用できます。ただし、「__」(半角アンダーライン 2 文字)ではじまる文字列は、 音声認識エンジン側で予約されていますので、「__」(半角アンダーライン 2 文字)ではじまる文字列は指定しないようにしてください。
単語登録リスト(profileWords)
profileWords=<URLエンコードされた値>
このセッションの認識処理で利用することを目的として、一時的に単語登録できます。ひとつの単語は『表記（半角スペース）読み』という形式で登録します。クラス名を指定する場合は、『表記<半角スペース>読み <半角スペース> クラス名』としてください。複数登録する場合は、単語と単語を「 | 」（半角縦棒）で区切ります。値のフォーマットは以下のようになります（クラス名を指定してない場合の例です）。
表記1 読み1|表記2 読み2|表記3 読み3|表記4 読み4
- 通常、マイページの単語登録画面で単語登録するほうが効率的です。単語登録画面での単語登録の仕方はプロファイルと単語登録についてを参照してください。
- profileWords で一時的に単語登録する場合には、profileId を指定する必要はありません。
- profileWords に沢山の単語を設定してクエリー文字列で送信すると、HTTP ヘッダのサイズ制限に抵触する場合があります。それを避けるためにも、
dパラメータはマルチパート方式で送信してください。 - profileId と profileWords の両方を指定する場合には、 profileId を先に指定する必要があります。
フィラー単語の出力指定(keepFillerToken)
keepFillerToken=1
発話に含まれるフィラー単語（「あー」や「えー」など）を自動的に除去したくないときに指定します。フィラー単語の前後は半角の「%」で囲まれています。
（例） %あー% %えー% %おー% %えーっと%
keepFillerToken=1 の指定をしていない場合、フィラー単語は認識結果から除去されています。
dパラメータの送信方法
d パラメータをマルチパート POST 送信する場合
リクエストをマルチパート POST する場合は、d パートのボディにdパラメータの値をそのまま記述します。"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 クエリ文字列として送信する場合
HTTP POST で、dパラメータをクエリー文字列として送信する場合は、上の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--
レスポンス
レスポンスの構造
<result>には、以下の JSON が格納されています。
| 説明 | |||
|---|---|---|---|
| results | 「発話区間の認識結果」の配列 ※配列形式ですが要素数は常に 1 個です。 | ||
| confidence | 信頼度(0 ～ 1 の値。 0:信頼度低, 1:信頼度高) | ||
| starttime | 発話開始時間 （音声データの先頭が 0） | ||
| endtime | 発話終了時間 （音声データの先頭が 0） | ||
| tags | 未使用（空配列） | ||
| rulename | 未使用（空文字） | ||
| text | 認識結果テキスト | ||
| tokens | 認識結果テキストの形態素の配列 | ||
| written | 形態素（単語）の表記 | ||
| confidence | 形態素の信頼度（認識結果の尤度） | ||
| starttime | 形態素の開始時間 （音声データの先頭が 0） | ||
| endtime | 形態素の終了時間（音声データの先頭が 0） | ||
| spoken | 形態素の読み *3 | ||
| utteranceid | 認識結果情報 ID *1 | ||
| text | 「発話区間の認識結果」の全てを結合した全体の認識結果テキスト | ||
| code | 結果を表す 1 文字のコード *2 | ||
| message | エラー内容を表す文字列 *2 |
*1 認識結果情報 ID は、WebSocket 音声認識プロトコルの場合は、発話区間毎の認識結果情報に付与された ID となります。HTTP 音声認識プロトコルの場合は、1 セッションでアップロードされた（複数の発話区間を含む可能性のある）音声データ全体の認識結果情報に付与された ID となります。
*2 認識成功時は body.code == "" かつ body.message == "" かつ body.text != "" 認識失敗時は body.code != "" かつ body.message != "" かつ body.text == ""
*3 日本語エンジンの認識結果の spoken は平仮名です。 英語エンジンの認識結果の spoken は読みではありません（無視してください）。 中国語エンジンの認識結果の spoken はピンイン（pinyin）です。
code と message の一覧
<result>に含まれる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” | 認識結果全体の信頼度が信頼度しきい値を下回ったために認識に失敗 ※ 受け取った音声データ全体から発話が 1 個も検出できなかったため認識結果を返却できない場合にも、このエラーが返却されます。発話検出に失敗する原因としては、音声データの欠損や音声データフォーマットの指定間違いが考えられます。 |
| “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” | クライアントから受信した音声データが音声データキューに入れられてからある一定時間以内に認識処理が完了しなかったために認識失敗 |
| “” | “” | 認識成功 |