非同期 HTTP インタフェース
非同期 HTTP インタフェースは長時間の音声をテキスト化、文字起こしするためのノンブロッキングな HTTP API です。
この API を利用するには以下のステップを実行します。
- 音声認識ジョブを作成する
- ポーリングして音声認識ジョブの状態をチェックし、結果を取得する
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 インタフェースでのみ有効なパラメータは以下の表のとおりです。
パラメータ名 | 値 | 説明 |
---|---|---|
loggingOptOut | True|False | ログ保存のあり、なしの変更を指定します。True に設定するとセッション中、システムはログを保存しません。デフォルトはFalse です。 |
contentId | 任意の文字列 | ユーザー側で定義した任意の文字列を指定できます。そのセッション中の状態、結果のレスポンスに含まれます。デフォルトでは設定されません。 |
compatibleWithSync | True|False | 結果フォーマットの互換性。同期 HTTP インタフェースと互換性のある形で結果をフォーマットします。デフォルトはFalse です。 |
speakerDiarization | True|False | 話者ダイアライゼーションの有効化オプション。話者ダイアライゼーションを有効にします。デフォルトはFalse です。 |
diarizationMinSpeaker | int | 話者ダイアライゼーションの最小推定話者人数。話者ダイアライゼーションが有効になっているときのみ有効で、音声に含まれる最小話者数を指定できます。1 以上に設定する必要があります。デフォルトは 1 です。 |
diarizationMaxSpeaker | int | 話者ダイアライゼーションの最大推定話者人数。話者ダイアライゼーションが有効になっているときのみ有効で、音声に含まれる最大話者数を指定できます。diarizationMinSpeaker 以上に設定する必要があります。デフォルトは 10 です。 |
sentimentAnalysis | True|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 となっているものは、その情報があればレスポンスに含まれます。
キー | q | s | p | c | e | 説明 |
---|---|---|---|---|---|---|
status | A | A | A | A | A | ジョブの状態。queued、started、processing、completed、error の状態をとる。 |
audio_md5 | A | A | O | 受信した音声ファイルの MD5 チェックサムの値。 | ||
audio_size | A | A | O | 受信した音声ファイルのサイズ。 | ||
content_id | O | O | O | O | O | ユーザーがリクエスト時に設定した contentId の値。 |
service_id | A | A | A | A | ユーザーID。 | |
segments | A | 音声認識プロセスの結果。発話単位の音声認識結果。 | ||||
utteranceid | A | 音声認識プロセスの結果。認識結果情報 ID。 | ||||
text | A | 音声認識プロセスの結果。「発話区間の認識結果」の全てを結合した全体の認識結果テキスト。 | ||||
code | A | 音声認識プロセスの結果。結果を表す 1 文字のコード。 | ||||
message | A | 音声認識プロセスの結果。エラー内容を表す文字列。 | ||||
error_message | A | エラー内容を表す文字列 |
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 ステータスコード | エラーメッセージ | 説明 |
---|---|---|
401 | No app_key | APPKEY が設定されていない |
401 | No authorization header | Authorization ヘッダが設定されていない |
401 | Invalid authorization header format | Authorization ヘッダのフォーマットが不正 |
401 | Failed to authorize for the app_key | 指定された APPKEY による認証が失敗 |
404 | Specified session_id is not found | 指定された session_id のジョブが見つからない。正しいsession_id を指定しているにも関わらず、このエラーが起きる場合、以下のようなケースが考えられます。- データ保存期間を過ぎたとき - リクエスト時のユーザーと異なったユーザーがジョブの状態や結果を取得しようとしたとき |
500 | - | 内部エラー。こちらにご連絡下さい。 |