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

非同期 HTTP インタフェース

非同期 HTTP インタフェースは長時間の音声をテキスト化、文字起こしするためのノンブロッキングな HTTP API です。

この API を利用するには以下のステップを実行します。

  1. 音声認識ジョブを作成する
  2. ポーリングして音声認識ジョブの状態をチェックし、結果を取得する

1 のジョブを生成する方法は、ログのあり・なしの指定方法などが異なりますが、同期 HTTP インタフェースとほぼ同じです。

エンドポイント

同期 HTTP インタフェースとは異なり、ログ保存のあり、なしに関わらずエンドポイントのベースは同じです。

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

1. ジョブの作成

エンドポイント:

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

リクエスト

リクエストの方法は、同期 HTTP インタフェースと同じです。詳細は同期 HTTP インタフェースリファレンスのリクエストを参照してください。

d パラメータについて

同期 HTTP インタフェースのdパラメータが設定できます。非同期 HTTP インタフェースでのみ有効なパラメータは以下の表のとおりです。

パラメータ名説明
loggingOptOutTrue|Falseログ保存のあり、なしの変更を指定します。Trueに設定するとセッション中、システムはログを保存しません。デフォルトはFalseです。
contentId任意の文字列ユーザー側で定義した任意の文字列を指定できます。そのセッション中の状態、結果のレスポンスに含まれます。デフォルトでは設定されません。
compatibleWithSyncTrue|False結果フォーマットの互換性。同期 HTTP インタフェースと互換性のある形で結果をフォーマットします。デフォルトはFalseです。
speakerDiarizationTrue|False話者ダイアライゼーションの有効化オプション。話者ダイアライゼーションを有効にします。デフォルトはFalseです。
diarizationMinSpeakerint話者ダイアライゼーションの最小推定話者人数。話者ダイアライゼーションが有効になっているときのみ有効で、音声に含まれる最小話者数を指定できます。1 以上に設定する必要があります。デフォルトは 1 です。
diarizationMaxSpeakerint話者ダイアライゼーションの最大推定話者人数。話者ダイアライゼーションが有効になっているときのみ有効で、音声に含まれる最大話者数を指定できます。diarizationMinSpeaker 以上に設定する必要があります。デフォルトは 10 です。
sentimentAnalysisTrue|False感情分析を有効にします。デフォルトはFalseです。

レスポンス

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

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

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

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

キー説明
results配列(要素 1 個)
tokens配列(空)
tags配列(空)
rulename文字列(空)
text文字列(空)
text文字列(空)
code結果を表す 1 文字のコード。レスポンスコードとメッセージを参照してください。
messageエラー内容を表す文字列。レスポンスコードとメッセージを参照してください。

{
"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ユーザーID。
segmentsA音声認識プロセスの結果。発話単位の音声認識結果。
utteranceidA音声認識プロセスの結果。認識結果情報 ID。
textA音声認識プロセスの結果。「発話区間の認識結果」の全てを結合した全体の認識結果テキスト。
codeA音声認識プロセスの結果。結果を表す 1 文字のコード。
messageA音声認識プロセスの結果。エラー内容を表す文字列。
error_messageAエラー内容を表す文字列

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

status が completed のときには音声認識の結果を JSON 形式で返します。同期 HTTP インタフェースと異なり、認識結果が発話単位で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 文字のコード。レスポンスコードとメッセージを参照してください。
messageエラー内容を表す文字列。レスポンスコードとメッセージを参照してください。

error(エラー)のレスポンスの詳細

音声認識処理に失敗したときのレスポンスの例です。それぞれの値はレスポンスに含まれる情報を参照してください。

{
"status": "error",
"audio_md5":"40f59fe5fc7745c33b33af44be43f6ad",
"audio_size":306980,
"service_id":"{YOUR_SERVICE_ID}",
"session_id":"017c25ec12c00a304474a999",
"error_message": "ERROR: Failed to transcribe in recognition process - amineth_result=0, amineth_code='o', amineth_message='recognition result is rejected because confidence is below the threshold'"
}

エラーレスポンス

ジョブの状態の確認、結果の取得のエンドポイントの呼び出しに失敗した場合は、HTTPステータスコードが200以外を返します。レスポンスのボディには以下の情報を持つJSONデータを返します。

パラメータ名説明
errorCodeレスポンスコード。
errorMessageエラーメッセージ。

例:

{
"errorCode":401,
"errorMessage":"Invalid authorization header format"
}
ステータスコードとエラーメッセージ

呼び出しが失敗した場合のステータスコードとエラーメッセージは以下のとおりです。

HTTP ステータスコードエラーメッセージ説明
401No app_keyAPPKEY が設定されていない
401No authorization headerAuthorization ヘッダが設定されていない
401Invalid authorization header formatAuthorization ヘッダのフォーマットが不正
401Failed to authorize for the app_key指定された APPKEY による認証が失敗
404Specified session_id is not found指定された session_id のジョブが見つからない。正しいsession_idを指定しているにも関わらず、このエラーが起きる場合、以下のようなケースが考えられます。
- データ保存期間を過ぎたとき
- リクエスト時のユーザーと異なったユーザーがジョブの状態や結果を取得しようとしたとき
500-内部エラー。こちらにご連絡下さい。