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

非同期 HTTP インタフェース

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

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

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

利用の方法

1. 音声認識ジョブを作成する

ジョブの作成の API リクエストは、同期 HTTP 音声認識 API と同じようにリクエストパラメータを設定し、非同期 HTTP 音声認識 API のエンドポイントにリクエストを送信します。

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

例えば、curl コマンドで、ログ保存なしで、test.wavファイルの音声認識のリクエストを送るには以下のようにします。

curl -X POST https://acp-api-async.amivoice.com/v1/recognitions \
-F u={APP_KEY} \
-F d="grammarFileNames=-a-general loggingOptOut=True" \
-F a=@test.wav

同期 HTTP 音声認識 API とはエンドポイントが異なりますが、リクエストパラメータの設定の方法は同じです。

note

いくつかのパラメータは非同期 HTTP 音声認識 API にしか対応していません。例えば、2022年6月現在では、話者ダイアライゼーションや感情解析は非同期 HTTP にしか対応していないためです。

caution

同期 HTTP 音声認識 API とは異なり、ログ保存のあり、なしはエンドポイントではなく、リクエストパラメータで指定します。 デフォルトではログ保存ありとなります。ログ保存をしないようにするには、dパラメータにloggingOptOut=Trueを指定します。

成功した場合

成功時のレスポンスにはsessionidが含まれています。これは、ユーザの音声認識リクエストに対するジョブの ID でジョブの状態を確認したり、結果を得るために利用します。 textは常に"..."を返します。

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

失敗した場合

失敗時のレスポンスにはsessionidが含まれません。codemessageで失敗の原因を判断できます。 レスポンスコードとメッセージを参照ください。

{
"results": [{ "tokens": [], "tags": [], "rulename": "", "text": "" }],
"text": "",
"code": "-",
"message": "received illegal service authorization"
}

2. 音声認識ジョブの状態をチェックし、結果を取得する

ジョブの状態の取得

ジョブはサーバ側で順次実行されます。ジョブの状態の確認や、結果を取得するには結果取得用のエンドポイント GET /v1/recognitions/{session_id}に問い合わせます。

sessionidには、ジョブ作成時に得られたジョブ ID を設定します。リクエストパラメータの認証情報(authorization)は、Authorizationヘッダーに指定してください。

curl で実行する場合は以下のようにします。ここでは、sessionid017c25ec12c00a304474a999だとします。

$ curl -H "Authorization: Bearer {AppKey}" \
https://acp-api-async.amivoice.com/v1/recognitions/017c25ec12c00a304474a999

queued 状態

リクエストを送った直後は、statusqueuedの状態になります。

{"service_id":"{YOUR_SERVICE_ID}","session_id":"017c25ec12c00a304474a999","status":"queued"}

started 状態

キューからジョブが取り出されるとstatusstarted状態になります。

{"service_id":"{YOUR_SERVICE_ID}","session_id":"017c25ec12c00a304474a999","status":"started"}

processing 状態

実際に音声認識処理が始まるとstatusprocessing状態になります。以下のサンプルを参照ください。ここでは見やすさのために結果を改行しています。 API が受けとった音声のサイズ(audio_size)や、MD5 チェックサム(audio_md5)を使って音声が正しく送信できたかを確認できます。

processingから次のcompleted状態になるまでにかかる時間は、音声の長さによりますが、だいたい音声の長さの0.5〜1.5倍程度を目安にしてください。

{
"audio_md5":"40f59fe5fc7745c33b33af44be43f6ad",
"audio_size":306980,
"service_id":"{YOUR_SERVICE_ID}",
"session_id":"017c25ec12c00a304474a999",
"status":"processing"
}

completed 状態

音声認識が完了すると、statuscompleted状態となります。このとき、レスポンスのresultssegmentsに音声認識結果を得ることができます。結果は音声認識サーバの処理が完了してから一定期間サーバに保存されます。保存期間は、非同期HTTP音声認識APIの制限の"音声認識結果の保存期間"を参照してください。

認識結果を含むレスポンスの詳細は音声認識の結果を参照してください。

note

一定期間を過ぎて削除された結果にアクセスすると、404 NOT FOUNDエラーとなります。エラーについてはリファレンスのエラーレスポンス一覧を参照してください。

error 状態

なんらかの理由で音声認識が失敗した場合は、statuserror状態となります。音声認識の結果のリクエストに成功したら、statuscompletedとなるかerrorとなるまでポーリングしてください。errorの原因についてはレスポンスコードとメッセージを参照してください。

コンテンツ ID

リクエスト時にdパラメータのcontentIdには自由に文字列を設定できます。例えば、アプリケーションが発行した ID や、ファイル名、利用者などの情報を設定しておくことで、認識結果の一部として後からそれらの情報が得られます。

例えば、curl コマンドでcontentIdにファイル名を設定してリクエストを送るには以下のようにします。

curl -X POST https://acp-api-async.amivoice.com/v1/recognitions \
-F u={APP_KEY} \
-F d="grammarFileNames=-a-general loggingOptOut=True contentId=test.wav" \
-F a=@test.wav

ジョブの状態や結果を取得する際、以下のようにcontent_idが含まれるようになります。

{"content_id":"test.wav","service_id":"{YOUR_SERVICE_ID}","session_id":"017c25ec12c00a304474a999","status":"queued"}