非同期 HTTP 音声認識 API
非同期 HTTP 音声認識 API は長時間の音声をテキスト化、文字起こしするためのノンブロッキングな HTTP API です。
この API を利用するには以下のステップを実行します。
- 音声認識ジョブを作成する
- ポーリングして音声認識ジョブの状態をチェックし、結果を取得する
1 のジョブを生成する方法は、ログのあり・なしの指定方法などが異なりますが、同期 HTTP 音声認識 API とほぼ同じです。
エンドポイント
同期 HTTP 音声認識 API とは異なり、ログ保存のあり、なしに関わらずエンドポイントのベースは同じです。
https://acp-api-async.amivoice.com/v1/recognitions
1. ジョブの作成
エンドポイント：
POST https://acp-api-async.amivoice.com/v1/recognitions
リクエスト
リクエストの方法は、同期 HTTP 音声認識 APIと同じです。詳細は同期 HTTP 音声認識 API リファレンスのリクエストを参照してください。ただし、非同期 HTTP 音声認識 API でのみ設定できるdパラメータがありますので、以下も参照してください。
d パラメータについて
非同期 HTTP 音声認識 API でのみ有効なパラメータは以下のとおりです。
・ログ保存のあり、なしの変更（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 文字のコード。レスポンスコードとメッセージを参照してください。 | |
| 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 | ユーザ名。 | |
| segments | A | 音声認識プロセスの結果。発話単位の音声認識結果。 | ||||
| utteranceid | A | 音声認識プロセスの結果。認識結果情報 ID。 | ||||
| text | A | 音声認識プロセスの結果。「発話区間の認識結果」の全てを結合した全体の認識結果テキスト。 | ||||
| code | A | 音声認識プロセスの結果。結果を表す 1 文字のコード。 | ||||
| message | A | 音声認識プロセスの結果。エラー内容を表す文字列。 | ||||
| error_message | A | エラー内容を表す文字列 |
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 文字のコード。レスポンスコードとメッセージを参照してください。 | |||
| message | エラー内容を表す文字列。レスポンスコードとメッセージを参照してください。 |
エラーレスポンス
| 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 | - | 内部エラー。こちらにご連絡下さい。 |