非同期 HTTP インタフェース
非同期 HTTP インタフェースは長時間の音声をテキスト化、文字起こしするためのノンブロッキングな HTTP API です。
この API を利用するには以下のステップを実行します。
- 音声認識ジョブを作成する
- ポーリングして音声認識ジョブの状態をチェックし、結果を取得する
1 のジョブを生成する方法は、ログのあり・なしの指定方法などが異なりますが、同期 HTTP イ ンタフェースとほぼ同じです。
エンドポイント
同期 HTTP インタフェースとは異なり、ログ保存のあり、なしに関わらずエンドポイントのベースは同じです。
v2（新版）の場合
https://acp-api-async.amivoice.com/v2/recognitions
v1（従来版）の場合
https://acp-api-async.amivoice.com/v1/recognitions
v1 と v2 の違いについては、新しいバージョンについてを参照してください。
- 古いバージョンの非同期 HTTP インタフェースは、今後停止される予定です。ご利用中の方は、v2 への移行を行ってください。
- v2 では現在、感情分析の機能を利用することができません。感情分析を利用する場合は、v1 をご利用ください。
1. ジョブの作成
エンドポイント：
v2（新版）の場合
POST https://acp-api-async.amivoice.com/v2/recognitions
v1（従来版）の場合
POST https://acp-api-async.amivoice.com/v1/recognitions
リクエスト
リクエストの方法は、同期 HTTP インタフェースと同じです。詳細は同期 HTTP インタフェースリファレンスのリクエストを参照してください。
d パラメータについて
同期 HTTP インタフェースのｄパラメータが設定できます。非同期 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/v2/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 | - | 内部エラー。こちらにご連絡下さい。 |