Qwen-Audio Realtime API は、WebSocket プロトコルを介してリアルタイムの音声会話機能を提供します。クライアントは、JSON イベントを送受信することでサーバーと対話します。この API は、音声入力、テキスト入力、音声区間検出 (VAD)、ストリーミングによる音声およびテキスト出力をサポートしています。
ユーザーガイド：リアルタイムオーディオチャット (Qwen-Audio-Realtime)。クライアントイベントとサーバーイベントの詳細については、クライアントイベントおよびサーバーイベントをご参照ください。
重要Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールの各リージョン向けにワークスペース固有ドメインをリリースしました。これらの新しい専用ドメインにより、推論リクエストのパフォーマンスと安定性が向上します。以下の新しいドメインへの移行を推奨します：
- 中国 (北京)：
dashscope.aliyuncs.comから{WorkspaceId}.cn-beijing.maas.aliyuncs.comへ - シンガポール：
dashscope-intl.aliyuncs.comから{WorkspaceId}.ap-southeast-1.maas.aliyuncs.comへ
{WorkspaceId} を実際の ワークスペース ID に置き換えてください。既存のドメインは引き続き問題なく利用できます。
サービスエンドポイント
WebSocket の URL は以下の通りです。model クエリパラメーターを使用してモデル名を指定します (<model_name> を実際のモデル名に置き換えてください)：
シンガポール
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
{WorkspaceId} (波括弧を含む) を実際のワークスペースIDに置き換えてください。
中国 (北京)
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
{WorkspaceId} (波括弧を含む) を実際のワークスペースIDに置き換えてください。
重要wss:// プロトコルを使用してください。リクエストヘッダーに Authorization を設定します。モデル名は model URL クエリパラメーターで渡します。
リクエストヘッダー
リクエストに以下のヘッダーを含めてください：
パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
Authorization | string | はい | 認証トークンです。形式は |
user-agent | string | いいえ | サーバー側でリクエストを追跡するためのクライアント識別子です。 |
X-DashScope-WorkSpace | string | いいえ | Alibaba Cloud Model Studio のワークスペースIDです。 |
重要Authorization は WebSocket のハンドシェイク中に検証されます。API キーが無効な場合、または存在しない場合、ハンドシェイクは HTTP 401/403 エラーで失敗します。
基本概念
- セッション：単一の WebSocket 接続が 1 つのセッションに対応し、設定と会話のコンテキストを維持します。
- 会話アイテム：会話内の個々のメッセージで、順番に管理されます。
- レスポンス：単一のモデル推論によって生成される出力で、1 つ以上のアウトプットアイテムを含みます。アウトプットアイテムには、アシスタントメッセージや関数呼び出しがあります。
- 関数呼び出し：モデルがクライアントにツール関数の実行を要求する必要がある場合に生成するアウトプットアイテムです。クライアントがツールを実行した後、結果を
function_call_outputで送信し、response.createで次の推論をトリガーします。 - ターン検出：モデル推論をトリガーするタイミングを制御します。
インタラクションモード
Qwen-Audio Realtime API は 3 つのインタラクションモードをサポートしており、session.update イベントの turn_detection.type パラメーターで設定します：
モード | turn_detection.type | 説明 | ユースケース |
|---|---|---|---|
server_vad |
| サーバー側 VAD が発話の開始と終了を検出し、自動的に推論をトリガーします。 | ハンズフリー会話、音声アシスタント |
smart_turn |
| 音響分析と意味分析を組み合わせ、音声信号だけでなく意味的な内容も考慮してターンの境界を判断するインテリジェントなターン検出です。「あー」や「えー」などの非意味的な音は、ターンをトリガーしたり、再生を中断したりしません。 | 低遅延の自然な会話、高品質な割り込み |
プッシュツートーク |
| クライアントが手動で音声を送信し、推論をトリガーします。 | プッシュツートーク、精密な制御 |
インタラクションフロー
クライアントイベントとサーバーイベントの詳細については、クライアントイベントとサーバーイベントをご参照ください。
server_vad モード
サーバーは受信した音声に対して音声区間検出を行い、発話の終了を検出した後に自動的に推論をトリガーします。
有効化の方法：session.update イベントの turn_detection.type を server_vad に設定します。
完全な会話ターン
以下の図は、server_vad モードでの典型的なインタラクションシーケンスを示しています：
インタラクションは次のように進行します：
- クライアントが WebSocket 接続を確立すると、サーバーは
session.createdイベントを返します。 - クライアントは
session.updateを送信してセッションパラメーターを設定し、サーバーはsession.updatedを返します。 - クライアントは継続的に
input_audio_buffer.appendを送信して音声データをストリーミングします。 - サーバーは発話の開始を検出し、
input_audio_buffer.speech_startedを返します。また、conversation.item.input_audio_transcription.deltaを介して ASR による文字起こしの差分をストリーミングします。 - サーバーは発話の終了を検出し、
input_audio_buffer.speech_stopped、input_audio_buffer.committed、およびconversation.item.createdを返します。 - サーバーは自動的にレスポンスを生成し、テキストと音声の差分 (
response.audio_transcript.delta、response.audio.delta) をストリーミングし、最終的にresponse.doneを返します。
ユーザーによる割り込み (バージイン)
モデルがレスポンスを再生中に VAD がユーザーの発話開始を検出した場合、サーバーは現在のレスポンスをキャンセルし (ステータスが cancelled の response.done を返します)、新しい音声入力とレスポンスのやり取りを開始します。次の図は、ユーザーによる割り込み (バージイン) のインタラクションシーケンスを示しています：
smart_turn モード
smart_turn モードは、音響分析と意味分析を組み合わせて発話の終了を検出し、相槌、背景ノイズ、その他の非意味的な音をフィルタリングします。非意味的な音は、会話のターンをトリガーすることなく、conversation.item.ambient_audio_transcription.delta イベントとして送信されます。
有効化の方法：session.update イベントの turn_detection.type を smart_turn に設定します。
完全な会話ターン
次の図は、smart_turn モードでの一般的なインタラクションシーケンスを示しています：
server_vad mode との主な相違点:
- 非意味的な音 (「あー」、「えー」など) は推論をトリガーしません。代わりに、
conversation.item.ambient_audio_transcription.deltaイベントを通じて返されます。 - 以前に検証された発話が取り消されることがあり (
input_audio_buffer.speech_stoppedがreason=turn_invalidを返します)、その場合、推論はトリガーされません。 - ユーザーの次の入力を待っている間、クライアントは明示的に
response.createを送信して推論をトリガーできます。
ユーザーによる割り込み (バージイン)
バージイン処理は、server_vad モードの場合とほぼ同じです。次の図は、ユーザーのバージインインタラクションシーケンスを示しています。
無効なターン
以前に検証された発話が取り消されることがあり (input_audio_buffer.speech_stopped が reason=turn_invalid を返します)、その場合、推論はトリガーされません。クライアントは音声の送信を続け、次の有効な発話を待つ必要があります。次の図は、無効なターンのインタラクションシーケンスを示しています：
話者強調設定フロー
smart_turn モードでは、最初の session.update に voiceprint_audio_urls が含まれている場合、サーバーは非同期で声紋登録 (対象話者の音声特徴の読み込み) を実行し、イベントを通じてクライアントに登録の進捗を通知します。声紋登録に失敗しても、通常の会話フローはブロックされません。
声紋登録のインタラクションシーケンスは次のとおりです：
-
クライアントは、
turn_detection.voiceprint_audio_urlsに声紋音声 URL を含めてsession.updateを送信します。サーバーはsession.createdを返します。 -
サーバーは直ちに非同期で声紋登録を開始し、
session.updatedを返す前にvoiceprint_audio_list.in_progressをプッシュします。このイベントには、登録タスクを一意に識別するitem_idが含まれます。 -
サーバーは
session.updatedを返し、セッション設定が有効になったことを確認します。 -
登録が完了すると、サーバーは終了イベントをプッシュします (ステップ 2 の
item_idと一致します)：- 登録成功：
voiceprint_audio_list.completed。 - 登録失敗：
voiceprint_audio_list.failed。失敗を説明するreasonフィールドが含まれます (例：音声URLがダウンロードできなかった)。
- 登録成功：
注記voiceprint_audio_urls は、最初の session.update イベントでのみ設定可能です。後続の session.update 呼び出しでは、このフィールドは無視されます。
プッシュツートーク モード
クライアントは手動で音声の送信と推論のトリガーを制御します。音声がいつ送信され、推論がいつ開始されるかを正確に制御する必要がある場合に、このモードを使用します。
有効化の方法：session.update イベントの turn_detection を null に設定します。
完全な会話ターン
次の図は、プッシュツートーク モードにおける典型的なインタラクションシーケンスを示しています：
インタラクションは次のように進行します：
- クライアントは継続的に
input_audio_buffer.appendを送信して音声データをストリーミングします。 - ユーザーが話し終えた後、クライアントは
input_audio_buffer.commitを送信してバッファをコミットします。 - クライアントは
response.createを送信して手動で推論をトリガーします。 - サーバーはレスポンスを生成し、テキストと音声をストリーミングします。
ユーザーによる割り込み (バージイン)
クライアントは response.cancel を送信して現在のレスポンスをキャンセルし、サーバーは response.done (ステータス cancelled、理由 client_cancelled) を返します。次の図は、ユーザーによる割り込み (バージイン) のインタラクションシーケンスを示しています：
各モードでの操作の制約
操作 | プッシュツートーク | server_vad | smart_turn |
|---|---|---|---|
session.update | アイドル状態ではすべてのパラメーターを変更できます。アイドル状態以外では一部が制限されます。 | アイドル状態ではすべてのパラメーターを変更できます。アイドル状態以外では一部が制限されます。 | アイドル状態ではすべてのパラメーターを変更できます。アイドル状態以外では一部が制限されます。 |
input_audio_buffer.append | 許可 | 許可 | 許可 |
input_audio_buffer.commit | 許可 | 無視 | 無視 |
input_audio_buffer.clear | 許可 | 無視 | 無視 |
response.create | 許可。最初に | レスポンスが生成されていない場合は許可。レスポンス生成中は許可されません。 | ユーザーの次の入力を待っている間は許可。アクティブなターン ( |
response.cancel | 許可 (推論中) | 許可 (推論中) | 許可 (推論中) |
conversation.item.create/delete/retrieve | 許可 | 許可 | 許可 |
注記turn_detection および input_audio_format は、最初の音声が送信される前 (アイドル状態) にのみ変更できます。
エラー処理
タイプ | 動作 | 例 |
|---|---|---|
クライアントエラー ( | 接続は維持され、クライアントはエラーイベントを受信します | 無効なパラメーター、許可されていない状態、重複した item_id |
サーバーエラー ( | 接続は終了します | LLM 接続の失敗、ストレージの失敗 |