Qwen-Audio-Realtime WebRTC アクセス
WebRTC はメディアトラックで音声を転送し、DataChannel でモデルイベントとテキストを転送します。Web クライアントはブラウザーのネイティブ API を使用でき、その他のクライアントは標準 WebRTC 対応ライブラリを使用できます。Model Studio は専用の WebRTC SDK を提供していません。
このドキュメントでは、このモデルの WebRTC アクセス手順と、ブラウザー側の完全なサンプルを示します。
このドキュメントは 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 に対応しています。サンプルでは
ブラウザーは業務 AppServer に Offer SDP を送信します。AppServer は API キーを使用して次のリクエストを転送し、Answer SDP をそのままブラウザーに返します。長期 API キーはフロントエンドに渡りません。
以下はブラウザー側の完全なサンプルです。まず、認証と SDP の交換の説明に従って業務 AppServer の
AppServer で対象モデル、リージョン、ワークスペースに応じた SDP 交換を設定します。以下は標準 Realtime 接続のパラメーターです。アプリケーション固有のパラメーターは、対応するベストプラクティスに従ってください。
リージョン、アドレス、認証の詳細は、認証と SDP の交換をご覧ください。業務 AppServer のインターフェイスは業務側で実装するもので、Model Studio の SDK API には含まれません。
Web 側では
方向はクライアントから見たものです。WebRTC トランシーバーで送受信をネゴシエートします。
たとえば、音声対話では通常、双方向の音声を使用します。Offer SDP には音声メディアセクション
この表はアプリケーションに必要なメディア方向を示すもので、すべての組み合わせを個別にネゴシエートできることを保証するものではありません。実際の設定は対象モデルとサーバーのネゴシエーション機能に依存します。
Offer 作成前に必要な方向をネゴシエートします。初期化確認が必要なモデルでは、取得したトラックを接続せずに送信機能を確保します。モデルの準備完了後、対応する sender の
次の例は双方向の音声を示します。
Offer の作成前に DataChannel を作成して、SDP にデータチャネルのネゴシエーションを含めます。クライアントとサーバーがチャネルの作成を処理する方法は、データチャネルでのイベント送受信をご覧ください。
DataChannel は、モデル初期化、テキスト、制御イベントの送信と、モデルの結果、状態、エラーの受信を担います。メディアトラックは音声の転送を担います。
完全なサンプルでは、Offer の作成前にクライアントイベントチャネルを作成し、サーバー側のチャネルコールバックを登録します。
次の順序で接続を完了します。
接続とイベントチャネルが利用可能になったら、対象モデルのプロトコルに従って初期化します。サーバーの初期化イベントを保持し、チャネル状態と組み合わせて処理を進めます。コールバックの到着順序が固定されているとは想定しないでください。
たとえば、
次の例は、
モデルの準備が整ったら、必要な上り音声トラックを接続します。リモートトラックのコールバックでモデル出力を処理し、DataChannel から返されるイベントを継続的に解析します。
接続が不要になったら、アプリケーションが所有するローカルキャプチャトラックを停止し、DataChannel と
シリアライズしたイベントを
クライアントが作成したチャネルとサーバーが作成したチャネルに同じバインド関数を使用します。この関数は転送と JSON 解析を担当し、セクション 5 の
次のルールにも従ってください。
適用範囲
このドキュメントは 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 に対応しています。サンプルでは qwen-audio-3.1-realtime-plus を使用します。
- 選択したリージョンとワークスペースに対応する API キーとワークスペース IDを使用してください。
- 北京のドメイン:
{WorkspaceId}.cn-beijing.maas.aliyuncs.com。シンガポールのドメイン:{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。 - 長期 API キーはサーバー側に保存し、ブラウザーやモバイルアプリケーションに含めないでください。一時 API キーの生成方法と権限は、一時 API キーの生成をご覧ください。
認証と SDP の交換
ブラウザーは業務 AppServer に Offer SDP を送信します。AppServer は API キーを使用して次のリクエストを転送し、Answer SDP をそのままブラウザーに返します。長期 API キーはフロントエンドに渡りません。
- メソッド:
POST
POST
https://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plusPOST
https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus- リクエストヘッダー:
Authorization: Bearer <API_KEY>、Content-Type: application/sdp - リクエストボディ:Offer SDP の文字列。
- 成功時のレスポンス:HTTP 200。ボディに Answer SDP が含まれます。失敗時は 4xx を返します。
/api/realtime/sdp は、業務 AppServer が構築するカスタムインターフェイスです。前述の転送処理を実装する必要があり、Model Studio が提供する URL ではありません。
処理フロー

- AppServer に API キーと対象モデルのパラメーターを用意します。
- クライアントの接続オブジェクトを作成し、コールバックを登録します。
- 上りメディアトラックを接続せずに、メディア方向と DataChannel を設定します。
- AppServer 経由で SDP を交換し、接続とイベントチャネルの準備完了を待ちます。
- モデルのプロトコルに従って設定します。確認後、必要な上りメディアトラックを接続します。
- 対話終了時にキャプチャを停止し、接続を閉じてリソースを解放します。
- 音声は WebRTC のメディアトラックで転送します。アプリケーションは、ローカル音声トラックの取得、リモートプレーヤーのバインド、対象モデルのイベント定義に従った DataChannel メッセージの送受信を行います。
- WebRTC の認証は SDP 交換時に行うため、AOQ トークンの取得は不要です。長期 API キーをフロントエンドに置かないよう、AppServer 経由で認証と SDP を中継します。
-
接続成功は転送チャネルの確立を示しますが、モデルの初期化完了を意味しません。このページの
qwen-audio-3.1-realtime-plusを使用する場合は、session.updateを送信し、session.updatedを受信してから、必要な上りメディアの送信を開始してください。
完全なサンプル
以下はブラウザー側の完全なサンプルです。まず、認証と SDP の交換の説明に従って業務 AppServer の /api/realtime/sdp インターフェイスを実装します。次に、業務 AppServer と同じオリジンでこの HTML ページを開き、プロトコル、ホスト、ポートを一致させます。たとえば、ページと /api/realtime/sdp の両方を http://localhost:3000 から配信します。API キーの保存と SDP の転送はサーバーが行い、長期 API キーをページに含めないでください。「Start」で接続し、対話の終了時に「End」でリソースを解放します。このサンプルは一度に 1 つの接続を確立します。別のセッションを開始するには、ページを再読み込みしてください。
1. 認証と接続パラメーターの準備
AppServer で対象モデル、リージョン、ワークスペースに応じた SDP 交換を設定します。以下は標準 Realtime 接続のパラメーターです。アプリケーション固有のパラメーターは、対応するベストプラクティスに従ってください。
| 設定項目 | 値 |
|---|---|
| メソッド | POST |
| URL | https://{endpoint}/api/v1/webrtc/realtime?model={model_name} |
Content-Type | application/sdp |
Authorization | Bearer <API_KEY> |
| リクエストボディ | Offer SDP |
| 成功時のレスポンス | Answer SDP |
2. 接続オブジェクトの初期化とコールバックの登録
Web 側では RTCPeerConnection を作成します。その他のプラットフォームでは、対応するライブラリを初期化します。接続前に、次のハンドラーを登録してください。
- 接続状態の変化:接続の成功、失敗、切断を判定します。
- DataChannel の確立、オープン、メッセージ、クローズ:モデルイベントを扱います。
- リモートメディアトラック:音声の受信と再生、または対象アプリケーションがサポートするその他のメディアの処理を行います。
txt という名前のチャネルでイベントを送信するため、datachannel コールバックを処理する必要があります。
3. メディア方向と DataChannel の設定
音声の方向の選択
方向はクライアントから見たものです。WebRTC トランシーバーで送受信をネゴシエートします。sendrecv は双方向、sendonly は送信のみ、recvonly は受信のみです。利用可能な機能はサーバーの SDP 応答とモデルの対応状況にも依存します。
| 方向 | 設定 |
|---|---|
| 音声を送信 | 音声送信機能をネゴシエートし、マイクまたは外部音声トラックを準備します。モデルの準備が整ってからトラックを接続します。 |
| 音声を受信— | 音声受信機能をネゴシエートし、リモートトラックのコールバックで音声再生をバインド |
m=audio が必要です。業務で音声再生が不要であっても、このセクションを削除しないでください。
このモデルのメディア方向
| モデルまたはアプリケーション | 音声送信 | 音声受信 | 映像送信 | 映像受信 |
|---|---|---|---|---|
| Qwen-Audio-Realtime | 音声入力用に有効化 | 音声出力用に有効化 | 非対応 | 非対応 |
送信せずにメディアを準備
Offer 作成前に必要な方向をネゴシエートします。初期化確認が必要なモデルでは、取得したトラックを接続せずに送信機能を確保します。モデルの準備完了後、対応する sender の replaceTrack で送信を開始します。メディア受信ハンドラーは事前に登録してください。
音声の送信と受信は、必要に応じて個別に設定します。マイクの有効化、音声の再生、モデルの初期化を 1 つの操作にまとめないでください。
メディア設定の例
次の例は双方向の音声を示します。media の 2 つのスイッチが、それぞれ音声の送信と受信を制御します。addTransceiver で方向を事前にネゴシエートし、キャプチャしたトラックはモデルの準備が整うまでローカルに保存してから送信側に接続します。
コードは、完全なサンプルをご覧ください。
イベントチャネルの作成
Offer の作成前に DataChannel を作成して、SDP にデータチャネルのネゴシエーションを含めます。クライアントとサーバーがチャネルの作成を処理する方法は、データチャネルでのイベント送受信をご覧ください。
DataChannel は、モデル初期化、テキスト、制御イベントの送信と、モデルの結果、状態、エラーの受信を担います。メディアトラックは音声の転送を担います。
完全なサンプルでは、Offer の作成前にクライアントイベントチャネルを作成し、サーバー側のチャネルコールバックを登録します。
4. 接続の確立
次の順序で接続を完了します。
createOfferとsetLocalDescriptionを呼び出します。- サーバーがサポートする ICE 方式に従って候補情報を収集します。このサンプルでは、ICE の収集が完了してからローカル SDP を送信します。
- ローカル SDP を業務 AppServer に送信します。AppServer は API キーを使用して Model Studio の SDP 交換インターフェイスを呼び出します。
- HTTP ステータスを確認し、成功時は返された Answer SDP を指定して
setRemoteDescriptionを呼び出します。 - 接続状態が成功に変わるのを待ち、モデルイベントの送信に使用する DataChannel がオープンしていることを確認します。
setRemoteDescription の完了は、対応するネゴシエーション手順の完了を示すだけで、メディア接続の成功を直接示すものではありません。また、DataChannel が open 状態でない場合は、モデルイベントを送信できません。
接続コードと状態コールバック
connectionstatechange で接続状態を判定し、icegatheringstatechange でローカル SDP の完成を待ちます。モデルの初期化には DataChannel の open とモデルの準備完了イベントも必要です。SDP 交換の完了だけで判断しないでください。
完全なサンプルでは、startSession() で SDP 交換を完了し、接続状態コールバックで接続結果を処理します。
業務 AppServer は、セクション 1 のアドレスとリクエストヘッダーに従って Offer を転送します。サンプル API はプレーンな SDP テキストを返す想定です。HTTP レスポンスヘッダー、ログ、JSON ラッパーを含む内容を、そのまま setRemoteDescription に渡さないでください。
5. モデルイベントとメディアの交換
モデルの初期化
接続とイベントチャネルが利用可能になったら、対象モデルのプロトコルに従って初期化します。サーバーの初期化イベントを保持し、チャネル状態と組み合わせて処理を進めます。コールバックの到着順序が固定されているとは想定しないでください。
たとえば、session.update でモデルを設定する場合は、そのプロトコルに従ってイベントを構築し、設定の確認を待ってから入力を送信します。音声、出力モダリティ、VAD、サンプリングレートなどのパラメーターは、現在のモデルのドキュメントに従ってください。
session.created はセッションの作成を示し、設定の適用完了を一律に示すものではありません。セッション設定の確認が必要なモデルでは、session.updated を待ってください。
モデルイベントの定義は、クライアントイベントとサーバーイベントをご覧ください。メディアの転送と利用可能なモードは、このページの説明に従ってください。
モデルイベントの例
音声はメディアトラックで転送し、WebSocket のメディア送信イベントは使用しません。
qwen-audio-3.1-realtime-plus の session.created → session.update → session.updated フローを示します。モデルのイベントリファレンスに従ってフィールドを設定します。設定完了を確認する session.updated を受信してから、上り音声トラックを接続してください。
コードは、完全なサンプルをご覧ください。
サンプルのモデル qwen-audio-3.1-realtime-plus では、音声出力を有効にすると response.audio.done でモデルの音声生成状態を監視できます。このイベントは、クライアントの音声再生の完了を示すものではありません。
メディア送受信の開始
モデルの準備が整ったら、必要な上り音声トラックを接続します。リモートトラックのコールバックでモデル出力を処理し、DataChannel から返されるイベントを継続的に解析します。
-
音声は RTP メディアトラックで転送するため、
input_audio_buffer.appendは不要です。 - DataChannel はテキスト、状態、制御、エラーイベントを転送します。
startSendingMedia() が上りトラックを接続し、ontrack が受信メディアを処理します。
6. 対話の終了とリソースの解放
接続が不要になったら、アプリケーションが所有するローカルキャプチャトラックを停止し、DataChannel と RTCPeerConnection を閉じ、プレーヤーを解放してアプリケーション状態をクリアします。
接続失敗や予期しない切断後はモデルの準備完了状態をクリアします。新しい接続では以前のセッション状態を再利用せず、モデルを再初期化してください。
完全なサンプルでは、endSession() が接続とメディアリソースを解放します。
ユーザーが終了ボタンをクリックしたとき、またはページを閉じるときに endSession() を呼び出します。
データチャネルでのイベント送受信
シリアライズしたイベントを send で送信する前に、チャネルが open であることを確認します。サーバーが作成したチャネルのイベントも含め、受信メッセージを message コールバックで解析します。
送信するイベントの名前、フィールド、パラメーター、タイミングは、対象モデルのクライアントイベント定義に従います。受信後の解析、状態変化、結果、エラー処理は、モデルのサーバーイベント定義に従います。初期化イベントはモデルの要件に応じて送信し、その後のテキストイベントや制御イベントはアプリケーションの必要に応じて送信してください。
DataChannel の例
クライアントが作成したチャネルとサーバーが作成したチャネルに同じバインド関数を使用します。この関数は転送と JSON 解析を担当し、セクション 5 の handleModelEvent がモデルの意味に応じた処理を行います。sendModelEvent は、モデルのプロトコルで許可される場合にのみ初期化、テキスト、制御イベントに使用します。
完全なサンプルでは、sendModelEvent() と bindDataChannel() でイベントを送受信します。
完全なサンプルでは、開始ボタンが startSession() を、終了ボタンが endSession() を呼び出します。これらはサンプルで定義した関数で、WebRTC の組み込み API ではありません。
Qwen-Audio-Realtime のイベント定義
| モデルまたはアプリケーション | クライアントイベント(送信) | サーバーイベント(受信) |
|---|---|---|
| Qwen-Audio-Realtime | クライアントイベント | サーバーイベント |
-
イベントの
typeフィールドでモデルイベントを識別し、関連する識別子はこのモデルのイベントリファレンスに従って処理します。 - モデルが必要とする初期化の確認、入力のコミット、レスポンスのキャンセル、タスクの完了などの操作は、対応するプロトコルに従って Data チャネル内で処理します。これらはモデルの対話動作であり、トランスポート接続の切断とは別の操作です。
- 音声データはメディアトラックで転送します。モデルのイベントリファレンスを使用する場合、メディアのカプセル化と使用可能な対話モードはこのページに従ってください。WebSocket のメディア送信方法をそのまま適用しないでください。