リアルタイム音声認識 API リファレンス - Intelligent Speech Interaction

リアルタイム音声認識は、WebSocket を介して連続的な音声ストリームを受信し、認識結果を返します。会議、スピーチ、ライブビデオストリームなど、長時間実行されるシナリオをサポートします。このトピックでは、エンドポイント、リクエストパラメーター、認識イベント、およびステータスコードについて説明します。

課金と同時実行数制限

リアルタイム音声認識は、トライアル版と商用版として利用できます。課金の詳細については、「課金項目」をご参照ください。

注意事項

API を呼び出す前に、音声フォーマット、サンプルレート、およびプロジェクトモデルが次の要件を満たしていることを確認してください。

サポートされる入力：PCM、PCM エンコード WAV、または Ogg Opus 形式の 16 ビットモノラル音声。
サポートされるサンプルレート：8,000 Hz および 16,000 Hz。
設定可能な出力機能には、中間認識結果、後処理での句読点追加、漢数字のアラビア数字への変換が含まれます。
話者ダイアライゼーションと話者役割分析はサポートされていません。
プロジェクトモデルは、認識言語または方言を決定します。リクエストパラメーターで指定することはできません。モデルの設定手順については、「プロジェクトの管理」をご参照ください。

エンドポイント

アクセスタイプ	説明	URL
インターネットアクセス	シンガポールリージョンのエンドポイントを使用します。	wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1

対話ワークフロー

説明

サーバー応答の header.task_id フィールドは、認識タスクを識別します。トラブルシューティングのためにこの値を記録してください。

1. 認証

サーバーへの WebSocket 接続を確立する際に、NLS トークンを使用して認証します。

手順については、「SDK を使用したトークンの取得」をご参照ください。

2. 認識の開始

認識パラメーターを含む StartTranscription コマンドを送信します。サーバーが TranscriptionStarted を返した後に音声のストリーミングを開始します。SDK を使用する場合、対応するメソッドを通じてパラメーターを設定します。次の表にパラメーターを説明します。

パラメーター	型	必須	説明
appkey	String	はい	Intelligent Speech Interaction コンソールで作成されたプロジェクトの Appkey。
format	String	いいえ	音声フォーマット：pcm、wav、または opus。
sample_rate	Integer	いいえ	音声サンプルレート。デフォルト：16,000 Hz。コンソールで、音声サンプルレートとユースケースをサポートするモデルでプロジェクトを設定します。
enable_intermediate_result	Boolean	いいえ	中間認識結果を返すかどうかを指定します。デフォルト：false。
enable_punctuation_prediction	Boolean	いいえ	後処理中に句読点を追加するかどうかを指定します。デフォルト：false。
enable_inverse_text_normalization	Boolean	いいえ	逆テキスト正規化 (ITN) を有効にして漢数字をアラビア数字に変換するかどうかを指定します。デフォルト：false。
customization_id	String	いいえ	カスタム言語モデルの ID。
vocabulary_id	String	いいえ	カスタムホットワード語彙の ID。
max_sentence_silence	Integer	いいえ	文境界検出の無音しきい値 (ミリ秒単位)。音声が検出された後、このしきい値より長い無音があると文が終了します。有効値：200～2000。デフォルト：800。 `enable_semantic_sentence_detection` が有効な場合、このしきい値は無音ベースの文境界検出には使用されません。その値は、依然として許容範囲内である必要があります。無音時間は、データ送信が停止した後の待機時間からではなく、音声データから計算されます。無音ベースのセグメンテーションを使用するには、無音セグメントを含む音声の送信を続行してください。PCM 音声では、ゼロ値のサンプルで無音を表すことができます。
enable_words	Boolean	いいえ	単語情報を返すかどうかを指定します。デフォルト：false。
disfluency	Boolean	いいえ	フィラーワード (言い淀み) を除去するかどうかを指定します。デフォルト：false (無効)。
speech_noise_threshold	Float	いいえ	ノイズしきい値。有効値：[-1, 1]。この値は、次のように分類に影響します：値が -1 に近いほど、ノイズが音声として分類される可能性が高くなります。値が +1 に近いほど、音声がノイズとして分類される可能性が高くなります。重要これは高度なパラメーターです。慎重に調整し、効果を十分にテストしてください。
enable_semantic_sentence_detection	Boolean	いいえ	意味的文境界検出を有効にするかどうかを指定します。デフォルト：false。この機能を有効にする場合は、`enable_intermediate_result` を `true` に設定して中間結果も有効にしてください。

3. 認識結果の受信

音声のストリーミングを続け、認識イベントを受信します。次の JSON スニペットは、イベントメッセージの構造を示しています。

ヘッダーオブジェクトのフィールド：

パラメーター	型	説明
namespace	String	メッセージの名前空間。
name	String	イベント名。
status	Integer	リクエストが成功したかどうかを示すステータスコード。「ステータスコード」セクションをご参照ください。
status_text	String	ステータスメッセージ。
task_id	String	グローバルに一意なタスク ID。トラブルシューティングのためにこの値を記録してください。
message_id	String	メッセージ ID。

SentenceBegin

SentenceBegin イベントは、サーバーが文の開始を検出したことを示します。サービスは自動的に文の境界を検出します。例：

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "SentenceBegin",
                "status": 20000000,
                "message_id": "a426f3d4618447519c9d85d1a0d1****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 0
        }
}

ペイロードオブジェクトのフィールド：

パラメーター	型	説明
index	Integer	文インデックス。1 から始まり、文ごとにインクリメントされます。
time	Integer	これまでに処理された音声の持続時間 (ミリ秒単位)。

TranscriptionResultChanged

TranscriptionResultChanged イベントには、現在の文の更新された中間結果が含まれます。これらのイベントは、`enable_intermediate_result` が `true` の場合にのみ返されます。例：

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "TranscriptionResultChanged",
                "status": 20000000,
                "message_id": "dc21193fada84380a3b6137875ab****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 1835,
                "result": "The weather in",
                "confidence": 1.0,
                "words": [{
                        "text": "The",
                        "startTime": 630,
                        "endTime": 930
                }, {
                        "text": "weather",
                        "startTime": 930,
                        "endTime": 1110
                }, {
                        "text": "in",
                        "startTime": 1110,
                        "endTime": 1140
                }]
        }
}

このイベントでは、`header.name` は `TranscriptionResultChanged` であり、中間認識結果を示します。

ペイロードオブジェクトのフィールド：

パラメーター	型	説明
index	Integer	文インデックス。1 から始まり、文ごとにインクリメントされます。
time	Integer	これまでに処理された音声の持続時間 (ミリ秒単位)。
result	String	現在の文の認識結果。
words	List< Word >	現在の文の単語情報。`enable_words` が `true` である必要があります。
confidence	Double	認識結果の信頼度スコア。範囲は [0.0, 1.0] です。値が高いほど信頼度が高いことを示します。

SentenceEnd

SentenceEnd イベントは、サーバーが文の終わりを検出したことを示し、その文の認識結果を返します。例：

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "SentenceEnd",
                "status": 20000000,
                "message_id": "c3a9ae4b231649d5ae05d4af36fd****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 1820,
                "begin_time": 0,
                "result": "The weather in Beijing.",
                "confidence": 1.0,
                "words": [{
                        "text": "The",
                        "startTime": 630,
                        "endTime": 930
                }, {
                        "text": "weather",
                        "startTime": 930,
                        "endTime": 1110
                }, {
                        "text": "in Beijing",
                        "startTime": 1110,
                        "endTime": 1380
                }]
        }
}

このイベントでは、`header.name` は `SentenceEnd` であり、文の終わりを示します。

ペイロードオブジェクトのフィールド：

パラメーター	型	説明
index	Integer	文インデックス。1 から始まり、文ごとにインクリメントされます。
time	Integer	これまでに処理された音声の持続時間 (ミリ秒単位)。
begin_time	Integer	対応する `SentenceBegin` イベントの時刻 (ミリ秒単位)。
result	String	認識結果。
words	List< Word >	現在の文の単語情報。`enable_words` が `true` である必要があります。
confidence	Double	認識結果の信頼度スコア。範囲は [0.0, 1.0] です。値が高いほど信頼度が高いことを示します。

各 `words` エントリのフィールド：

パラメーター	型	説明
text	String	単語のテキスト。
startTime	Integer	単語の開始時刻 (ミリ秒単位)。
endTime	Integer	単語の終了時刻 (ミリ秒単位)。

4. 認識の終了

すべての音声を送信した後、StopTranscription を送信して認識タスクを終了します。サーバーは残りの音声を処理し、タスクが終了すると TranscriptionCompleted を返します。このイベントを受信した後にのみ接続を閉じてください。

StopTranscription は、タスクを実行し続けたまま文の境界を強制するものではありません。残りの音声に有効な音声が含まれている場合、サーバーはタスクを完了する前に SentenceEnd を返すことがあります。無音のみを含むタスクは、必ずしも SentenceEnd を返すわけではありません。

ステータスコード

応答の header.status と header.status_text を使用して、リクエストのステータスを確認します。次の表に、一般的なエラーと解決策を示します。

一般的なエラーコード

ステータスコード	ステータスメッセージ	原因	解決策
40000000	デフォルトのクライアントエラーコード。複数のエラーメッセージがこのコードを使用できます。	無効なパラメーターまたはリクエストロジック。	リクエストをドキュメント化されたサンプルコードと比較し、修正したリクエストをテストします。
40000001	The token 'xxx' has expired; The token 'xxx' is invalid	一般的なクライアントエラーで、通常は期限切れまたは無効なトークンが原因です。	リクエストをドキュメント化されたサンプルコードと比較し、修正したリクエストをテストします。
40000002	Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!	無効または不正な形式のメッセージ。	リクエストをドキュメント化されたサンプルコードと比較し、修正したリクエストをテストします。
40000003	PARAMETER_INVALID; Failed to decode url params	無効なリクエストパラメーター。このエラーは、RESTful リクエストで一般的に発生します。	リクエストをドキュメント化されたサンプルコードと比較し、修正したリクエストをテストします。
40000005	Gateway:TOO_MANY_REQUESTS:Too many requests!	同時リクエストが多すぎます。	利用可能な同時実行クォータ内に収まるように、同時認識リクエストを減らします。
40000009	Invalid wav header!	無効なヘッダー。	`format` を `wav` に設定して WAV ファイルを送信する場合、WAV ヘッダーが有効であることを確認してください。そうでない場合、サーバーは音声を拒否する可能性があります。
40000009	Too large wav header!	送信された音声に無効な WAV ヘッダーが含まれています。	PCM や Opus などのフォーマットを使用してください。WAV 音声の場合、ヘッダーに正しいデータ長が含まれていることを確認してください。
40000010	Gateway:FREE_TRIAL_EXPIRED:The free trial has expired!	トライアル期間が終了し、商用版が有効化されていないか、アカウントに支払い遅延があります。	サービスの有効化とアカウント残高を確認してください。
40010001	Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal	サポートされていない API またはパラメーター。	API ドキュメントとリクエストパラメーターを照合し、エラーメッセージに基づいて修正してください。たとえば、curl で RESTful リクエストを行う場合は URL を確認してください。
40010003	Gateway:DIRECTIVE_INVALID:[xxx]	一般的なクライアントエラー。	クライアントが無効なパラメーターまたはコマンドを送信しました。API 固有のエラー詳細とドキュメントを使用してリクエストを修正してください。
40010004	Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!	リクエストが完了する前にクライアントが接続を閉じました。	`TranscriptionCompleted` を受信した後に接続を閉じます。
40010005	Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!	クライアントが現在の状態でサポートされていないコマンドを送信しました。	コマンドシーケンスを確認してください。タスクが停止中に `StopTranscription` を再度送信しないでください。
40020105	Meta:APPKEY_NOT_EXIST:Appkey not exist!	指定された Appkey が存在しません。	コンソールのプロジェクト設定で Appkey を確認してください。
40020106	Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!	Appkey とトークンが異なるアカウント UID に属しています。	Appkey とトークンが同じアカウントに属していることを確認してください。あるアカウントの Appkey を別のアカウントのトークンと一緒に使用しないでください。
403	Forbidden	トークンが存在しない、または期限切れなどの理由で無効です。	有効なトークンを指定してください。現在のトークンの有効期限が切れる前に新しいトークンを取得してください。
41000003	MetaInfo doesn't have end point info	Appkey のルーティング情報を取得できませんでした。	Appkey とトークンが同じアカウントに属していることを確認してください。あるアカウントの Appkey を別のアカウントのトークンと一緒に使用しないでください。
41010101	UNSUPPORTED_SAMPLE_RATE	サポートされていないサンプルレート。	リアルタイム音声認識は、8,000 Hz と 16,000 Hz のサンプルレートをサポートしています。
41040201	Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously!	サーバーがクライアントからのデータを待機中にタイムアウトしました。	リアルタイムレートで音声を継続的に送信してください。すべての音声を送信した後、`StopTranscription` を送信し、`TranscriptionCompleted` を待ってから接続を閉じてください。
50000000	GRPC_ERROR:Grpc error!	サーバーの負荷やネットワーク状態などの要因による断続的なエラー。	リクエストを再試行してください。
50000001	GRPC_ERROR:Grpc error!	サーバーの負荷やネットワーク状態などの要因による断続的なエラー。	リクエストを再試行してください。
52010001	GRPC_ERROR:Grpc error!	サーバーの負荷やネットワーク状態などの要因による断続的なエラー。	リクエストを再試行してください。

リアルタイム音声認識のエラーコード

ステータスコード	ステータスメッセージ	原因	解決策
40000004	Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time	クライアントは接続を確立してから 10 秒以上データを送信しませんでした。	接続を確立した後、キャプチャされた音声を継続的にストリーミングします。すべての音声を送信した後、`StopTranscription` を送信し、`TranscriptionCompleted` を待ってから接続を閉じてください。
40270002	NO_VALID_AUDIO_ERROR	無効な音声。	音声から有効なテキストが認識されませんでした。
40270003	DECODE_ERROR	音声のデコードに失敗しました。	`format` を実際の音声フォーマットに合わせて設定してください。
41000002	APPKEY_KEY_IS_NULL	`appkey` パラメーターが正しく設定されていません。	API ドキュメントとサンプルコードをご参照ください。