短文音声認識 API リファレンス - Intelligent Speech Interaction

短文音声認識は、最大 60 秒の音声クリップをテキストに変換し、チャット会話、音声コマンド、音声入力、音声検索などに利用できます。クライアントは WebSocket 経由で音声ストリームを送信し、認識イベントと結果を受信します。

注意事項

音声エンコーディングはリクエストパラメーターと一致させる必要があります。一致しない場合、認識が失敗したり、空の結果が返されたりする可能性があります。

チャンネルとビット深度：モノラル、16 ビット。
音声フォーマット：PCM、PCM エンコードされた WAV、OGG コンテナ内の OPUS、OGG コンテナ内の SPEEX、および AMR。
サンプルレート：8000 Hz または 16000 Hz。プロジェクトモデルは、音声のサンプルレートと言語をサポートしている必要があります。
音声の長さ：最大 60 秒。
音声サイズ：最大 2 MB。

リクエストパラメーターを使用して、中間結果、句読点、逆テキスト正規化 (ITN) などの機能を制御します。

認識モデルの選択

言語モデルと方言モデルはリクエストパラメーターで指定できません。Intelligent Speech Interaction コンソールの [すべてのプロジェクト] ページで、対象のプロジェクトを見つけて [プロジェクト機能の設定] をクリックします。音声の言語とサンプルレートに一致するモデルを選択します。設定手順については、「プロジェクトの管理」をご参照ください。

利用可能なモデルは、プロジェクト機能の設定ページに一覧表示されます。サンプルレートを選択し、次に言語モデルを選択します。

エンドポイント

パブリックネットワーク経由では、次の WebSocket エンドポイントを使用します： wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1。

インタラクションプロセス

WebSocket とこのプロトコルを使用する SDK には、次のプロセスが適用されます。RESTful リクエストについては、「RESTful API」をご参照ください。

すべてのサーバーイベントには、その header に認識タスクの task_id が含まれます。この ID を使用して、リクエストと応答を関連付け、問題のトラブルシューティングを行います。

1. 認証

クライアントは、WebSocket 接続を確立する際に NLS トークンを使用して認証します。

手順については、「アクセストークンの取得」をご参照ください。

2. 認識の開始

クライアントは、認識パラメーターを含む StartRecognition ディレクティブを送信します。サーバーはリクエストを検証し、RecognitionStarted イベントを返します。音声データを送信する前に、このイベントを待つ必要があります。

3. データの送信

クライアントは、サーバーイベントを受信しながら、バイナリ音声をチャンクで送信します。

enable_intermediate_result が true の場合、サーバーは中間結果を含む複数の RecognitionResultChanged イベントを返すことがあります。
enable_intermediate_result が false の場合、サーバーは中間結果を返しません。ただし、クライアントは RecognitionCompleted や TaskFailed などのイベントを処理する必要があります。

重要
最後の中間結果は、最終結果と異なる場合があります。RecognitionCompleted の結果を最終結果として使用してください。

4. 認識の停止

音声の送信後、クライアントは StopRecognition ディレクティブを送信します。成功した場合、サーバーは最終結果を含む RecognitionCompleted を返します。失敗した場合は TaskFailed を返します。接続を閉じる前に、サーバーからの完了または失敗イベントを待ってください。

音声区間検出が有効な場合、後続のサイレンスが max_end_silence を超えると、サーバーは認識を完了させることがあります。認識完了後に送信された音声は認識されません。

リクエストパラメーター

SDK では、SpeechRecognizer オブジェクトのメソッドを使用してこれらのパラメーターを設定します。直接 WebSocket リクエストを行う場合は、リクエストの header に appkey を設定し、その他の認識パラメーターを StartRecognition の payload に設定します。

パラメーター	タイプ	必須	説明
appkey	文字列	はい	コンソールで作成されたプロジェクトのアプリケーションキーです。
format	文字列	いいえ	音声フォーマット：`pcm`、`wav`、`opus`、`speex`、または `amr`。 WAV は PCM エンコーディングを使用する必要があります。OPUS と SPEEX は OGG コンテナを使用する必要があります。
sample_rate	整数	いいえ	サンプルレート (Hz)。デフォルト値：`16000`。有効な値：`8000` と `16000`。この値は、音声およびプロジェクトモデルと一致する必要があります。
enable_intermediate_result	ブール値	いいえ	中間認識結果を返すかどうか。デフォルト値：`false`。
enable_punctuation_prediction	ブール値	いいえ	後処理中に句読点を追加するかどうか。デフォルト値：`false`。
enable_inverse_text_normalization	ブール値	いいえ	逆テキスト正規化 (ITN) を有効にするかどうか。このパラメーターを `true` に設定すると、出力で漢数字がアラビア数字に変換されます。デフォルト値：`false`。
disfluency	ブール値	いいえ	フィラーワードをフィルターするかどうか (出力の平滑化)。デフォルト値：`false`。
customization_id	文字列	いいえ	カスタム言語モデルの ID。設定手順については、「カスタム言語モデル」をご参照ください。
vocabulary_id	文字列	いいえ	カスタムホットワードリストの ID。設定手順については、「カスタムホットワード」をご参照ください。
enable_voice_detection	ブール値	いいえ	音声区間検出 (VAD) を有効にするかどうか。VAD は発話の開始と終了を検出し、ノイズを除外します。デフォルト値：`false`。
max_start_silence	整数	いいえ	`enable_voice_detection` が `true` の場合にのみ有効です。先頭の無音の最大持続時間 (ミリ秒)。推奨範囲：(0, 60000]。この期間内に発話が検出されない場合、サーバーは `TaskFailed` を返し、認識を終了します。
max_end_silence	整数	いいえ	`enable_voice_detection` が `true` の場合にのみ有効です。末尾の無音の最大持続時間 (ミリ秒)。有効範囲：200～6000。末尾の無音がこの値を超えると、サーバーは `RecognitionCompleted` を返し、認識を終了します。後続の音声は認識されません。

応答イベント

header には、次の共通フィールドが含まれます。

パラメーター	型	説明
namespace	String	名前空間です。`SpeechRecognizer` です。
name	String	イベント名です。詳細については、後述のイベントの説明をご参照ください。
status	Integer	ステータスコードです。`20000000` は成功を示します。その他の値については、ステータスコードをご参照ください。
status_text	String	ステータスメッセージです。
task_id	String	グローバルに一意なタスク ID で、クライアントリクエストのタスク ID に対応します。トラブルシューティングのために、この値を記録してください。
message_id	String	このサーバー応答メッセージの ID です。

以下の中間および最終認識結果の例では、英語のサンプル音声を使用しています。

RecognitionStarted

サーバーが開始リクエストを受け付け、クライアントは音声データを送信できます。このイベントには認識結果は含まれません。

RecognitionResultChanged

payload.result フィールドには、中間認識結果が文字列として格納されます。このイベントは、enable_intermediate_result が true の場合にのみ返されます。

{
  "header": {
    "namespace": "SpeechRecognizer",
    "name": "RecognitionResultChanged",
    "status": 20000000,
    "message_id": "ae32ca6a437b45dca4e785156d74****",
    "task_id": "f393e1c6c946476f9233949cd0c6****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "result": "today is monday the weather is nice",
    "duration": 3049
  }
}

RecognitionCompleted

認識が正常に完了しました。payload.result フィールドには、最終認識結果が文字列として格納されます。

{
  "header": {
    "namespace": "SpeechRecognizer",
    "name": "RecognitionCompleted",
    "status": 20000000,
    "message_id": "9bf389630fd04d3c96a704c967e8****",
    "task_id": "f393e1c6c946476f9233949cd0c6****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "result": "today is monday, the weather is nice. ",
    "duration": 3049
  }
}

TaskFailed

認識タスクが失敗しました。原因については header.status と header.status_text を確認してください。例えば、音声を送信せずにリクエストを停止すると、40000000 と Gateway:CLIENT_ERROR:Empty audio data! が返されます。

状態コード

トラブルシューティングの際は、status と status_text の両方を確認してください。1 つの状態コードに複数の原因が考えられるため、特定のステータスメッセージを基に問題を特定してください。

一般的なエラーコード

状態コード	ステータスメッセージ	原因	ソリューション
40000000	クライアントのデフォルトのエラーコードです。このコードは複数のエラーメッセージに対応します。	無効なパラメーターまたは呼び出しシーケンス。	リクエストパラメーター、ディレクティブの順序、および特定のステータスメッセージを確認してください。
40000001	The token 'xxx' has expired. The token 'xxx' is invalid	トークンの有効期限が切れているか、無効です。	有効な NLS トークンを取得してリトライしてください。
40000002	Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!	メッセージが無効であるか、現在のタスクの状態で受け入れられません。	メッセージの構造とディレクティブの順序を確認してください。タスクが失敗した後は、新しい認識タスクを開始してください。
40000003	PARAMETER_INVALID Failed to decode url params	無効なパラメーター。	パラメーター名、型、および値が API 要件と一致しているか確認してください。
40000005	Gateway:TOO_MANY_REQUESTS:Too many requests!	同時リクエストが多すぎます。	同時リクエスト数を減らし、利用可能な同時実行数クォータを確認してください。
40000009	Invalid wav header!	メッセージヘッダーが無効です。	WAV 音声ファイルを送信し、`format` パラメーターを `wav` に設定した場合、音声ファイルの WAV ヘッダーが正しいか確認してください。ヘッダーが正しくない場合、サーバーはリクエストを拒否することがあります。
40000009	Too large wav header!	送信された音声の WAV ヘッダーが無効です。	音声ストリームは PCM や OPUS などのフォーマットで送信できます。WAV フォーマットを使用する場合は、音声ファイルの WAV ヘッダーに正しいデータ長が含まれていることを確認してください。
40000010	Gateway:FREE_TRIAL_EXPIRED:The free trial has expired!	商用版へのアップグレードが行われずにトライアル期間が終了したか、アカウントに支払い遅延があります。	コンソールで短文音声認識のアクティベーションステータスとアカウント残高を確認してください。
40010001	Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal	サポートされていない API またはパラメーターが使用されました。	エンドポイント、名前空間、およびパラメーターが API 要件と一致しているか確認してください。
40010003	Gateway:DIRECTIVE_INVALID:[xxx]	無効なパラメーターまたはディレクティブが送信されました。	特定のステータスメッセージを使用して、パラメーターとディレクティブを確認してください。
40010004	Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!	タスクが完了する前にクライアントが切断されました。	接続を閉じる前に、サーバーの完了または失敗イベントを待ってください。
40010005	Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!	現在のタスクの状態では、このディレクティブはサポートされていません。	ディレクティブの順序を確認し、重複した停止ディレクティブを送信しないようにしてください。
40020105	Meta:APPKEY_NOT_EXIST:Appkey not exist!	Appkey が存在しません。	コンソールでプロジェクト構成内の Appkey を確認してください。
40020106	Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!	Appkey とトークンが異なるアカウントに属しています。	同一アカウントのプロジェクト Appkey と NLS トークンを使用してください。
403	Forbidden	トークンが存在しない、有効期限が切れている、または無効です。	有効な NLS トークンを使用し、有効期限が切れる前に新しいトークンを取得してください。
41000003	MetaInfo doesn't have end point info	Appkey のルーティング情報を取得できませんでした。	Appkey を確認し、トークンと同じアカウントに属していることを確認してください。
41010101	UNSUPPORTED_SAMPLE_RATE	現在の構成では、このサンプルレートはサポートされていません。	8000 Hz または 16000 Hz の音声を使用し、音声、リクエストパラメーター、およびプロジェクトモデルが一致していることを確認してください。
50000000	GRPC_ERROR:Grpc error!	サーバー側の呼び出しが失敗しました。負荷またはネットワーク状態が原因である可能性があります。	リクエストをリトライしてください。問題が解決しない場合は、テクニカルサポートに連絡し、`task_id` を提供してください。
50000001	GRPC_ERROR:Grpc error!	サーバー側の呼び出しが失敗しました。負荷またはネットワーク状態が原因である可能性があります。	リクエストをリトライしてください。問題が解決しない場合は、テクニカルサポートに連絡し、`task_id` を提供してください。
52010001	GRPC_ERROR:Grpc error!	サーバー側の呼び出しが失敗しました。負荷またはネットワーク状態が原因である可能性があります。	リクエストをリトライしてください。問題が解決しない場合は、テクニカルサポートに連絡し、`task_id` を提供してください。

短文音声認識のエラーコード

状態コード	ステータスメッセージ	原因	ソリューション
40000000	Gateway:CLIENT_ERROR:Empty audio data!	音声データが送信されませんでした。	停止ディレクティブを送信する前に、空でないバイナリ音声データを送信してください。
40000004	Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time	WebSocket 接続が確立された後、データが送信されず、接続が 10 秒以上アイドル状態でした。	接続後、速やかに認識ディレクティブと音声を送信してください。すべての音声が送信されたら、停止ディレクティブを送信してください。
40010002	Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported!	サーバーはこのディレクティブをサポートしていません。	ディレクティブ名を確認し、短文音声認識でサポートされているディレクティブを使用してください。
40010003	Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173)	指定されたホットワードが多すぎます。	使用中のホットワード構成メソッドの制限値までホットワード数を減らしてください。
40270002	NO_VALID_AUDIO_ERROR	音声が無効で、有効なテキストが認識されませんでした。	音声に明瞭な発話が含まれていること、およびそのエンコーディング、サンプルレート、モデルが一致していることを確認してください。
41010104	TOO_LONG_SPEECH	音声が短文音声認識の時間制限を超えています。	最大 60 秒の音声を使用してください。それより長い音声の場合は、リアルタイム音声認識を使用してください。
41010105	SILENT_SPEECH	無音またはノイズの多い音声からは発話が検出されませんでした。	音声を確認してください。VAD が有効になっている場合は、先頭の無音部分の設定も確認してください。