Alibaba Cloud Model Studio:Qwen-Audio-Realtime WebSocket アクセス

Qwen-Audio-Realtime WebSocket アクセス

ユーザーガイド：リアルタイム音声対話（Qwen-Audio-Realtime）。詳細なイベント定義は、クライアントイベントとサーバーイベントをご覧ください。

対応モデル：qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash。

エンドポイント

以下の WebSocket URL を使用します。model クエリパラメーターでモデルを指定します。<model_name> をモデル名に置き換えてください：

中国（北京）

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

API の呼び出し時は、{WorkspaceId} をワークスペース ID に置き換えます。

シンガポール

wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

API の呼び出し時は、{WorkspaceId} をワークスペース ID に置き換えます。

リクエストヘッダー

リクエストヘッダーに次の情報を含めます。

パラメーター	型	必須	説明
Authorization	string	はい	形式が Bearer <your_api_key> の認証トークン。<your_api_key> を API キーに置き換えます。
user-agent	string	いいえ	リクエストの送信元の追跡に使用するクライアント識別子。
X-DashScope-WorkSpace	string	いいえ	Alibaba Cloud Model Studio のワークスペース ID。

汎用 WebSocket リファレンスには、データ検査用の X-DashScope-DataInspection ヘッダーも記載されています。モデルの要件に従って使用してください。qwen-audio-3.1-realtime-plus のサンプルでは、x-dashscope-dataInspection: disable を使用しています。

基本概念

• セッション：1 つの WebSocket 接続が 1 つのセッションに対応し、設定と対話コンテキストを保持します。
• 対話項目：対話内の各メッセージで、リンクリストとして構成されます。
• レスポンス：1 回のモデル推論の出力です。1 つのレスポンスには、アシスタントのメッセージや関数呼び出しなど、1 つ以上の出力項目が含まれます。
• 関数呼び出し：クライアントにツール関数の実行を求めるモデルからのリクエストです。関数の実行後、クライアントは結果を function_call_output として送信し、続いて response.create を送信して次の推論を開始します。
• ターン検出：推論を開始するタイミングを制御します。

対話モード

Qwen-Audio Realtime API は 3 つの対話モードをサポートします。session.update イベントの session.turn_detection で設定します。自動検出では、オブジェクト内の type を設定します。push-to-talk では、turn_detection フィールド全体を null に設定します。

モード	session.turn_detection の値	説明	ユースケース
server_vad	オブジェクト。type を server_vad に設定します。	サーバーが VAD で発話の開始と終了を検出し、自動的に推論を開始します。	ハンズフリーの会話と音声アシスタント
スマートな意味的ターン検出	オブジェクト。type を smart_turn または smart_turn_v2（推奨）に設定します。	音響認識と意味理解を組み合わせ、音声信号だけに依存せずターンの区切りを検出します。「uh」「ah」など意味を持たない音は、ターンを開始せず、モデルの再生も中断しません。	低レイテンシーの自然な会話と正確な割り込み処理
push-to-talk	null	クライアントが音声のコミットと推論の開始を手動で行います。	push-to-talk と精密な制御

対話フロー

イベント定義の詳細は、クライアントイベントとサーバーイベントをご覧ください。

server_vad モード

サーバーは入力音声に対して音声アクティビティ検出を行い、発話の終了を検出すると自動的に推論を開始します。

有効化：session.update イベントの turn_detection.type を server_vad に設定します。

対話の 1 ターン全体

次の図は、server_vad モードの一般的な対話シーケンスを示します。

クライアントとサーバーは次の順序でやり取りします。

1. クライアントが WebSocket 接続を確立します。サーバーは session.created を返します。
2. クライアントが session.update を送信してセッションを設定します。サーバーは session.updated を返します。
3. クライアントが input_audio_buffer.append を継続的に送信し、音声データを追加します。
4. サーバーが発話の開始を検出すると、input_audio_buffer.speech_started を返し、conversation.item.input_audio_transcription.delta で ASR 文字起こしの差分をストリーミングします。
5. サーバーが発話の終了を検出すると、input_audio_buffer.speech_stopped、input_audio_buffer.committed、conversation.item.created を返します。
6. サーバーが自動的にレスポンスを生成し、テキストと音声の差分（response.audio_transcript.delta と response.audio.delta）をストリーミングした後、response.done を返します。

ユーザーによる割り込み

モデルの音声再生中に VAD がユーザーの発話開始を検出すると、サーバーは現在のレスポンスをキャンセルし、ステータスが cancelled の response.done を返します。その後、音声入力と応答の新しいターンを開始します。次の図は、この割り込みシーケンスを示します。

smart_turn / smart_turn_v2 モード

このモードは音響認識と意味理解を組み合わせ、発話の終了を検出します。相づちや背景音など、意味を持たない音を除外できます。意味を持たない音は conversation.item.ambient_audio_transcription.delta イベントで返され、対話のターンを開始しません。

有効化：session.update イベントの turn_detection.type を smart_turn または smart_turn_v2 に設定します。

smart_turn_v2（推奨）：smart_turn を基に対話コンテキストの理解を強化し、複数人のシナリオで対話の意図をより正確に識別します。他の話者や無関係な発言による不要な応答と割り込みを減らします。

対話の 1 ターン全体

次の図は、smart_turn / smart_turn_v2 モードの一般的な対話シーケンスを示します。

server_vad モードとの主な違いは次のとおりです。

• 「uh」「ah」など意味を持たない音は推論を開始しません。ambient_audio_transcription イベントで返されます。
• 有効と判定された発話が無効になる場合があります。input_audio_buffer.speech_stopped が reason=turn_invalid を返す場合、推論は開始されません。
• ユーザーの次の入力を待っている間、クライアントは response.create を明示的に送信して推論を開始できます。

ユーザーによる割り込み

割り込み処理は基本的に server_vad モードと同じです。次の図は、割り込みシーケンスを示します。

無効なターン

有効と判定された発話が無効になる場合があります。input_audio_buffer.speech_stopped が reason=turn_invalid を返す場合、推論は開始されません。クライアントは音声の送信を続け、次の有効な発話入力を待ちます。次の図は、この無効なターンのシーケンスを示します。

話者強調の設定フロー

smart_turn / smart_turn_v2 モードで最初の session.update に voiceprint_audio_urls が含まれる場合、サーバーは対象話者の音声特徴を読み込み、声紋を非同期に登録します。登録の進捗はイベントで通知されます。登録に失敗しても、通常の対話は継続できます。

声紋の登録は次の順序で進みます。

1. クライアントが WebSocket 接続を確立します。サーバーは session.created を返します。

2. クライアントが最初の session.update を送信し、turn_detection.voiceprint_audio_urls で声紋音声の URL を指定します。

3. サーバーは直ちに声紋の非同期登録を開始します。session.updated を返す前に、一意の登録タスク識別子 item_id を含む voiceprint_audio_list.in_progress を送信します。

4. サーバーは session.updated を返し、セッション設定の適用を確認します。

5. 声紋登録の終了後、サーバーは終端イベントを送信します。その item_id は手順 3 の値と一致します。

   • 登録成功：voiceprint_audio_list.completed。
   • 登録失敗：voiceprint_audio_list.failed。ダウンロードできない音声 URL など、失敗理由を示す reason フィールドが含まれます。

プッシュツートーク モード

クライアントが、音声をコミットして推論を開始するタイミングを手動で制御します。このモードは push-to-talk 対話に適しています。

有効化：session.update イベントの turn_detection を null に設定します。

対話の 1 ターン全体

次の図は、push-to-talk モードの一般的な対話シーケンスを示します。

クライアントとサーバーは次の順序でやり取りします。

1. クライアントが input_audio_buffer.append を継続的に送信し、音声データを追加します。
2. ユーザーが話し終えた後、クライアントは input_audio_buffer.commit を送信してバッファをコミットします。
3. クライアントが response.create を送信し、推論を手動で開始します。
4. サーバーがレスポンスを生成し、テキストと音声をストリーミングします。

ユーザーによる割り込み

クライアントが response.cancel を送信し、現在のレスポンスをキャンセルします。サーバーは、ステータスが cancelled、理由が client_cancelled の response.done を返します。次の図は、この割り込みシーケンスを示します。

モード別の操作制限

操作	push-to-talk	server_vad	smart_turn / smart_turn_v2
session.update	IDLE 時はすべてのフィールドを変更可能。それ以外の状態では一部を制限	IDLE 時はすべてのフィールドを変更可能。それ以外の状態では一部を制限	IDLE 時はすべてのフィールドを変更可能。それ以外の状態では一部を制限
input_audio_buffer.append	使用可	使用可	使用可
input_audio_buffer.commit	使用可	無視	無視
input_audio_buffer.clear	使用可	無視	無視
response.create	input_audio_buffer.commit でバッファー内の音声をコミットした後に使用可能。レスポンスの生成中は別のレスポンスを開始しないでください。	レスポンスが生成されていない場合に使用可能。生成中は別のレスポンスを開始しないでください。	ユーザーの次の入力待ちで使用可能。input_audio_buffer.speech_started から response.done までのアクティブなターン内では、別のレスポンスを開始しないでください。
response.cancel	推論中に使用可能	推論中に使用可能	推論中に使用可能
conversation.item.create/delete/retrieve	使用可	使用可	使用可

エラー処理

ハンドシェイクに失敗した場合は、ドメイン、リージョン、ワークスペース、API キー、モデル名、モデルの有効化状態、権限を確認します。エラーの詳細は、エラーコードをご覧ください。

型	動作	例
クライアントエラー（invalid_request_error）	接続は維持され、エラーが通知される	無効なパラメーター、現在の状態で許可されていない操作、item_id の重複
サーバーエラー（server_error）	接続が終了する	LLM 接続の失敗またはストレージの障害

SDK とリファレンス

• Android SDK
• iOS SDK
• HarmonyOS SDK