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

1. ジョブのリクエスト

エンドポイント:

POST https://acp-api-async.amivoice.com/v1/recognitions

◆リクエスト

同期HTTP音声認識APIと同じパラメータを設定します。また、以下をdパラメータに設定できます。

リクエストパラメータ

・ログ保存のあり、なしの変更(loggingOptOut)
loggingOptOut=<True|False>
ログの保存のあり、なしを指定します。Trueに設定するとセッション中、システムはログを保存しません。デフォルトはFalseです。

ユーザ定義ID(contentId)
contentId=<任意の文字列>
ユーザ側で定義した任意の文字列を指定することができます。そのセッション中の状態、結果のレスポンスに含まれるようになります。デフォルトはNoneです。

・結果フォーマットの互換性(compatibleWithSync)
compatibleWithSync=<True|False>
同期HTTP音声認識APIと互換性のある形で結果をフォーマットします。デフォルトはFalseです。

・話者ダイアライゼーションの有効化オプション(speakerDiarization )
speakerDiarization=<True|False>
話者ダイアライゼーションを有効にします。デフォルトはFalseです。

・話者ダイアライゼーションの最小推定話者人数(diarizationMinSpeaker )
diarizationMinSpeaker=<int>
話者ダイアライゼーションが有効になっているときのみ有効で、音声に含まれる最小話者数を指定することができます。1以上に設定する必要があります。デフォルトは1です。

・話者ダイアライゼーションの最大推定話者人数(diarizationMaxSpeaker )
diarizationMaxSpeaker=<int>
話者ダイアライゼーションが有効になっているときのみ有効で、音声に含まれる最大話者数を指定することができます。diarizationMinSpeaker以上に設定する必要があります。デフォルトは10です。

◆レスポンス

成功時のレスポンスはJSONフォーマットで以下の値を持ちます。 

キー説明
sessionidユーザの音声認識リクエストに対するジョブのID。
text常に…を返します。

{"sessionid":"017ac8786c5b0a0504399999","text":"..."}

失敗時のレスポンスはJSONフォーマットで以下の値を持ちます。

キー説明
results  配列(要素1個)
tokens  配列(空)
tags  配列(空)
rulename  文字列(空)
text文字列(空)
text文字列(空)
code結果を表す1文字のコード
「JSONに含まれるcodeとmessage一覧」を参照のこと。
messageエラー内容を表す文字列
「JSONに含まれるcodeとmessage一覧」を参照のこと。

code、messageについては同期HTTP音声認識APIの詳細ページを参照ください。

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

2. ジョブの状態の確認、結果の取得

エンドポイント:

GET https://acp-api-async.amivoice.com/v1/recognitions/{session_id}

◆リクエスト

リクエストパラメータ

パラメータ名 必須送信方法説明
session_id必須パスパラメータジョブを作成のレスポンスで得られたIDを指定します。

認証

APPKEYはAuthorizationヘッダーに指定してください。

Authorization: Bearer {APPKEY}

◆レスポンス

リクエストに成功した場合、音声認識リクエストの状態statusと付随する情報を返します。失敗した場合は、HTTPのレスポンスコード200以外を返します。成功した場合の statusは以下の5つの値をとります。

status説明
queuedジョブがキューに登録された状態。
startedジョブがキューから取り出されて、実行環境を用意している状態。
processingジョブが実行されている状態。
completed音声認識プロセスから結果が得られた状態。codeが空文字、つまり音声認識に成功した場合、segmentsに結果が含まれます。
errorジョブを実行しようとしたとき、もしくは、ジョブの実行中に何らかのエラーが発生した状態。error_message にエラーの詳細を保存します。

レスポンスに含まれる情報

queued、started、processing、completed、errorの各状態で含まれる情報について以下の表に整理します。各状態のそれぞれの頭文字の欄(q, s, p, c, e)で、Aとなっているものは常に含まれます。Oとなっているものは、その情報があればレスポンスに含まれます。

キーqspce説明
statusAAAAAジョブの状態。queued、started、processing、completed、errorの状態をとる。
audio_md5AAO受信した音声ファイルのMD5チェックサムの値。
audio_sizeAAO受信した音声ファイルのサイズ。
content_idOOOOOユーザがリクエスト時に設定したcontentIdの値。
service_idAAAAユーザ名。
segmentsA音声認識プロセスの結果。発話単位の音声認識結果。
utteranceidA音声認識プロセスの結果。認識結果情報ID。
textA音声認識プロセスの結果。「発話区間の認識結果」の全てを結合した全体の認識結果テキスト。
codeA音声認識プロセスの結果。結果を表す1文字のコード。
messageA音声認識プロセスの結果。エラー内容を表す文字列。
error_messageAエラー内容を表す文字列

completed(音声認識結果)のレスポンスの詳細

statusがcompletedのときには音声認識の結果をJSON形式で返します。同期HTTP音声認識APIと異なり、認識結果が発話単位でsegmentsの下に配置されます。

キー説明
segments
results 「発話区間の認識結果」の配列 
 confidence 信頼度(0~1の値。 0:信頼度低, 1:信頼度高) 
starttime  発話開始時間  (音声データの先頭が0)
endtime  発話終了時間  (音声データの先頭が0)
tags  未使用(空配列)
rulename  未使用(空文字)
text認識結果テキスト
tokens  認識結果テキストの形態素の配列 
 written  形態素(単語)の表記 
confidence  形態素の信頼度(認識結果の尤度)
starttime  形態素の開始時間  (音声データの先頭が0)
endtime  形態素の終了時間(音声データの先頭が0) 
spoken  形態素の読み
label話者ラベル(speaker0, speaker1, …)
リクエスト時にspeakerDiarization=Trueが指定されたときのみ、結果に含まれます。
utteranceid 認識結果情報ID
text 「発話区間の認識結果」の全てを結合した全体の認識結果テキスト
code 結果を表す1文字のコード
「JSONに含まれるcodeとmessage一覧」を参照のこと。
message エラー内容を表す文字列
「JSONに含まれるcodeとmessage一覧」を参照のこと。

code、messageについては同期HTTP音声認識APIの詳細ページを参照ください。

エラーレスポンス

HTTPステータスコードエラーメッセージ説明
401No app_keyAPPKEYが設定されていない
401No authorization headerAuthorizationヘッダが設定されていない
401 Invalid authorization header formatAuthorizationヘッダのフォーマットが不正
401Failed to authorize for the app_key指定されたAPPKEYによる認証が失敗
404Specified session_id is not found指定されたsession_idが見つからない
500内部エラー。https://acp.amivoice.com/contact/acp/にご連絡下さい。