IBM Cloud Docs
音声認識要求の実行

音声認識要求の実行

IBM Watson® Speech to Text サービスによる音声認識を要求するには、書き起こす音声のみを提供する必要があります。 サービスの各インターフェース (WebSocket インターフェース、同期 HTTP インターフェース、および非同期 HTTP インターフェース) には同一の基本的な書き起こし機能が備わっています。

以下の例は、サービスの各インターフェースの基本的な書き起こし要求 (オプション・パラメーターなし) を示しています。

  • 例では、名前が「FLAC」という短いファイルを提出する audio-file.flac。
  • これらの例では、デフォルトの言語モデル en-US_BroadbandModel を使用します。 詳細は 、「デフォルトモデルの使用 」を参照してください。

音声認識の結果についてでは、これらの例に対するサービスの応答について説明します。

使用上の要件

音声認識要求を行う場合は、次の基本的な使用要件を考慮してください。

  • メソッド名には大/小文字の区別があります。
  • HTTP 要求ヘッダーには大/小文字の区別はありません。
  • HTTP および WebSocket 照会パラメーターには大/小文字の区別があります。
  • JSON フィールド名には大/小文字の区別があります。
  • すべての JSON 応答コンテンツは UTF-8 文字セットになります。
  • 資料では、変数値を示すために中括弧 ({ }) が使用されています。 変数値を指定する時には、中括弧を省略してください。

以下のサービス固有の要件も考慮してください。

  • 入力音声のみを指定する必要があります。 その他のすべてのパラメーターはオプションです。
  • 必要に応じて、model パラメーターを指定して、ご使用の言語と音声に適したモデルを示してください。
  • 入力の一部として無効なクエリー・パラメーターまたは JSON フィールドを指定した場合は、無効な引数について説明する warnings フィールドが応答に含められます。 警告に関係なく要求は成功します。

要求での音声の送信

サービスに渡す音声は、サービスでサポートされているフォーマットでなければなりません。 サービスはほとんどの音声のフォーマットを自動的に検出できます。 音声によっては、Content-Type またはこれに相当するパラメーターを使用してフォーマットを指定する必要があります。 詳しくは、音声フォーマットを参照してください。 (以下の例では、わかりやすくするために、すべての要求で音声フォーマットが指定されています。)

WebSocket インターフェースと同期 HTTP インターフェースでは、1 つの要求で最大 100 MB の音声データを渡すことができます。 非同期 HTTP インターフェースでは、最大 1 GB の音声データを渡すことができます。 要求で音声データを送信するときは、常に 100 バイト以上の音声データを送信する必要があります。

大量の音声を認識する場合は、音声を複数の小さなデータに手動で分割できます。 ただし、通常は音声を非可逆圧縮フォーマットに変換する方が効率的で便利です。 圧縮により、1 つの要求で送信できるデータの量を最大化できます。 特に音声が WAV または FLAC フォーマットの場合、非可逆フォーマットに変換するとかなりの差が出ます。

WebSocket インターフェースの使用

WebSocket インターフェースでは、全二重接続により低遅延と高いスループットを実現する効率的な実装が提供されます。 すべての要求と応答が、同一 WebSocket 接続を介して送信されます。

WebSocket インターフェースを使用するには、最初に /v1/recognize メソッドを使用してサービスとの接続を確立します。 この接続を介して送信される要求に使用する言語モデルやカスタム・モデルなどのパラメーターを指定します。 次に、サービスからの応答を処理するイベント・リスナーを登録します。 要求を行うには、音声フォーマットとその他の追加パラメーターを指定した JSON テキスト・メッセージを送信します。 音声をバイナリー・メッセージ (blob) として渡し、音声の終わりを示すテキスト・メッセージを送信します。

以下に、接続を確立して認識要求のテキスト・メッセージとバイナリー・メッセージを送信する JavaScript コードの例を示します。 基本的な例には、接続に必要なすべてのイベント・ハンドラーを定義するコードは含まれていません。

var access_token = {access_token};
var wsURI = '{ws_url}/v1/recognize'
  + '?access_token=' + access_token;
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };

function onOpen(evt) {
  var message = {
    action: 'start',
    content-type: 'audio/flac'
  };
  websocket.send(JSON.stringify(message));
  websocket.send(blob);
  websocket.send(JSON.stringify({action: 'stop'}));
}

同期 HTTP インターフェースの使用

同期 HTTP インターフェースでは、最も簡単に認識要求を行うことができます。 サービスに対して要求を行うには、POST /v1/recognize メソッドを使用します。 音声とすべてのパラメーターを 1 つの要求で渡します。 以下の curl の例は、基本的な HTTP 認識要求を示します。

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognize"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognize"

非同期 HTTP インターフェースの使用

非同期 HTTP インターフェースは、音声書き起こしのためのノンブロッキング・インターフェースです。 このインターフェースは、最初にサービスにコールバック URL を登録してもしなくても使用できます。 コールバック URL を指定すると、サービスはジョブ・ステータスと認識結果を含むコールバック通知を送信します。 このインターフェースは、ユーザー指定の秘密に基づく HMAC-SHA1 署名を使用して、通知のための認証とデータ保全性を確保します。 コールバック URL を指定しない場合は、ジョブ・ステータスと結果を確認するためにサービスをポーリングする必要があります。 いずれの場合でも、認証要求を行うには POST /v1/recognitions メソッドを使用します。

以下の curl の例は、単純な非同期 HTTP 認識要求を示します。 要求にはコールバック URL が指定されていないので、ジョブ・ステータスと結果の書き起こしを取得するためにサービスをポーリングする必要があります。

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognitions"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognitions"