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

非同期 HTTP 音声認識 API

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

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

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

1 のジョブを生成する方法は、ログのあり・なしの指定方法などが異なりますが、同期 HTTP 音声認識 API とほぼ同じです。

エンドポイント

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

  1. ジョブの作成

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

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 となっているものは、その情報があればレスポンスに含まれます。

キー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 文字のコード。レスポンスコードとメッセージを参照してください。
messageエラー内容を表す文字列。レスポンスコードとメッセージを参照してください。

エラーレスポンス

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-内部エラー。こちらにご連絡下さい。