Skip to main content

Qwen-Omni-Realtime AOQ アクセス

Qwen-Omni-Realtime AOQ アクセス

AOQ は音声・動画メディアとモデルイベントを別々のトラックで転送します。SDK はメディアのキャプチャ、エンコード・デコード、転送、再生を処理します。アプリケーションは Data トラックでモデルイベントを送信してレスポンスを処理します。このページは Qwen-Omni-Realtime のメディア方向とイベントプロトコルを使用します。

適用範囲

このドキュメントは Qwen-Omni-Realtime を対象とします。既存のアクセスドキュメントは qwen3.8-omni-flash-realtime、qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime を扱います。サンプルモデルは qwen3.8-omni-flash-realtime です。
  • 選択したリージョンとワークスペースに対応する API キーとワークスペース IDを使用してください。
  • 北京のドメイン：{WorkspaceId}.cn-beijing.maas.aliyuncs.com。シンガポールのドメイン：{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。
  • API キーはサーバーにのみ保存してください。ブラウザーやモバイルアプリケーションに埋め込まないでください。
  • マイクで音声、またはカメラで動画をキャプチャする場合は、プラットフォームの要件に従って必要な権限を要求してください。
  • SDK ダウンロードから、使用するプラットフォームの SDK をダウンロードしてください。

認証と接続認証情報

トークンを事前取得する場合や認証フロー全体を確認する場合は、接続認証の詳細を参照してください。
AppServer から次のリクエストを送信します。最初に API キーを環境変数として設定してください。下のリクエスト URL でリージョンを選択し、ワークスペース ID を入力します。clientIp は任意です。省略すると、ゲートウェイはリクエストの送信元 IP アドレスを使用します。
POSThttps://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime
POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime

export ENDPOINT="{WorkspaceId}.cn-beijing.maas.aliyuncs.com"
curl -X POST \
  "https://${ENDPOINT}/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "x-dashscope-rtc-transport: moq" \
  -d '{}'
クライアントのパブリック IP アドレスを指定するには、リクエストボディの -d '{}' を -d '{"clientIp":"<CLIENT_PUBLIC_IP>"}' に置き換えます。

リクエストのフィールド

設定項目

値

説明

endpoint

ユースケースに対応するエンドポイントドメインを選択

エンドポイントドメインを指定します。詳しくは、リージョン、デプロイ範囲、エンドポイントの選択をご覧ください。Token Plan を使用する場合は、エンドポイントドメインの WorkspaceId を token-plan に設定します。

Content-Type

application/json

メッセージのメディアタイプ

Authorization

Bearer <YOUR_API_KEY>

API キー

x-dashscope-rtc-transport

moq

AOQ プロトコルを選択

clientIp

クライアントのパブリック IP アドレス

任意です。省略すると、サービスはゲートウェイが受信したリクエストの送信元 IP アドレスを使用します。指定すると、clientIp を使用します。サービスはクライアントの IP アドレスに基づいて最適な Relay エンドポイントを選択します。

レスポンスの例 

{
    "sid": "1d06b55683db49bba67a407902f62d02:1782706970:69aecdc5...",
    "aoqTokenForClient": "ecc1a46015d5496ca4ff7a48281eb739",
    "clientRelayEndpoints": [{"endpoint": "121.199.XX.XX", "port": 8443, "route_index": 0}],
    "clientRelayCertFingerprint": "sha256/99843495...",
    "sidExpiresInSecs": 7200,
    "extraInfo": {"workspaceIdHash": "2021b6f98cea4cff"}
}

レスポンスのフィールド

フィールド

説明

sid

一意のセッション識別子です。

aoqTokenForClient

クライアント接続トークン。この値を SDK の token フィールドに渡します。

clientRelayEndpoints

Relay エンドポイントの配列です。レスポンス例の各要素には、次のフィールドが含まれます。
endpointRelay エンドポイントのアドレス。portRelay エンドポイントのポート。route_indexこのフィールドがない場合、以下の iOS サンプルでは配列のインデックスを使用します。

clientRelayCertFingerprint

Relay TLS 証明書のフィンガープリント。

sidExpiresInSecs

セッションの有効期間（秒）。

extraInfo

追加情報。
workspaceIdHashワークスペース ID のハッシュ。

AOQ Client SDK の接続例

clientIp は、リクエストボディ内の省略可能なフィールドです。指定されていない場合、Model Studio ゲートウェイにリクエストする IP アドレスがクライアント IP として使用されます。指定された場合、clientIp の値が優先されます。最適なリレーアクセスポイントを取得するには、お使いのビジネス AppServer でクライアントの実際の IP アドレスを取得し、渡してください。
iOS (Swift)
let resp = try JSONDecoder().decode(AllocateResponse.self, from: responseData)

let config = AoqConnectConfig()
config.token = resp.aoqTokenForClient
config.sid = resp.sid
config.certFingerprint = resp.clientRelayCertFingerprint
config.relayEndpoints = resp.clientRelayEndpoints.enumerated().map { index, item in
    let ep = AoqRelayEndpoint()
    // Fall back to the array index when route_index is missing
    ep.routeIndex = item.routeIndex ?? index
    ep.endpoint = item.endpoint
    ep.port = item.port
    return ep
}
config.workspaceIdHash = resp.extraInfo?.workspaceIdHash ?? ""

let audioTrack = AoqTrackParam()
audioTrack.trackType = .audio
let dataTrack = AoqTrackParam()
dataTrack.trackType = .data
config.publishTracks = [audioTrack, dataTrack]
config.subscribeTracks = [audioTrack, dataTrack]

engine.connect(config)

処理フロー

AOQ 接続シーケンス図
  1. AppServer 経由で接続認証情報を取得します。
  2. SDK エンジンを作成し、コールバックを登録します。
  3. メディアトラックと Data トラックを設定し、上りメディアの送信を無効にします。
  4. AOQ 接続を開始し、接続完了を待ちます。
  5. モデルのプロトコルに従って設定します。確認後、必要な上りメディアを有効にします。
  6. 対話が終了したら切断し、リソースを解放します。
  • AOQ SDK はメディアのキャプチャ、処理、送信、受信、再生を担当します。アプリケーションは対象モデルのイベント定義に従って Data メッセージを送受信する必要があります。
  • 接続成功はモデルへの転送チャネルの確立を示します。クライアントはモデルの初期化完了後に、必要な上りメディアを有効にします。このページのサンプルモデル qwen3.8-omni-flash-realtime では、session.update を送信し、session.updated を待ってからメディア転送を開始します。

1. 接続認証情報の取得

クライアントは AppServer に認証情報を要求します。AppServer はこのモデルの Realtime 接続エンドポイントを呼び出し、ゲートウェイへのリクエストに API キーと x-dashscope-rtc-transport: moq を含めます。エンドポイント、リクエスト、フィールドの詳細は、Token 認証をご覧ください。 応答を AoqConnectConfig に対応付けます。
ゲートウェイの応答SDK 設定
aoqTokenForClienttoken
sidsid
clientRelayCertFingerprintcertFingerprint
clientRelayEndpointsrelayEndpoints。各アクセスポイントを構造に従って変換
extraInfo contains workspaceIdHashworkspaceIdHash
新しい接続ごとに新しい認証情報を取得してください。同じ接続でセッションを再利用したり、別のタスクを開始したりできるかどうかは、対象モデルのプロトコルに依存します。

2. SDK の初期化とコールバックの登録

エンジンを作成し、接続状態、Data メッセージ、エラーのコールバックを登録します。以下は iOS の Swift の例です。 
let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)
AoqEngineDelegate を実装します。onConnectionStatusChange で接続状態を管理し、onDataMsg で対象モデルのイベントを解析し、onError で SDK エラーを処理してください。モデルから返されるエラーイベントは、Data メッセージの処理ロジック内で別途処理する必要があります。SDK インターフェイスとエラーの詳細は、プラットフォーム別 SDKと機能リファレンスをご覧ください。

3. SDK の設定

メディア方向の選択

方向はクライアントを基準にしています。アプリケーションが必要とする入出力モダリティだけを設定し、使用しない方向のトラックは追加しないでください。
方向設定項目一般的な用途
音声を送信Audio トラックを配信し、音声エンコーダーと内蔵または外部キャプチャを設定音声対話
音声を受信Audio トラックを購読し、音声デコーダーとプレーヤーまたは外部再生を設定音声レスポンス
動画を送信Video トラックを配信し、カメラまたは外部動画入力とエンコードパラメーターを設定視覚入力に対応するモデルに動画を送信
動画を受信このモデルは動画出力に非対応動画の購読を設定しない
Data トラックはこの 4 つの方向から独立しています。モデルイベントの送信には Data トラックを配信し、レスポンスの受信には購読します。テキストの入出力にも Data トラックが必要です。

このモデルのメディア方向

次の表は、このモデルのメディア方向を示します。モデルの範囲は、適用範囲をご覧ください。その他のアクセス方法は、Qwen-Omni-Realtimeをご覧ください。
モデルまたはアプリケーション音声送信音声受信映像送信映像受信
Qwen-Omni-Realtime音声入力が必要な場合に有効化音声応答が必要な場合に有効化視覚入力が必要な場合に有効化有効にできません

メディアパラメーターとトラックの設定

上り音声と下り音声を別々に設定します。上りには setAudioEncoderConfig、下りには setAudioDecoderConfig を使用します。これらはネットワーク転送を制御するパラメーターで、ゲートウェイがモデルに必要な形式に音声を変換します。転送時のエンコードは SDK の要件に、モデルイベント内の音声形式は対象モデルの要件に従って設定してください。 必要に応じて startAudioCapture、startAudioPlayer、startVideoCapture を開始します。カスタム入出力については後述の高度な機能を参照してください。 publishTracks はクライアントが送信するトラック、subscribeTracks はクライアントが受信するトラックです。
シナリオpublishTrackssubscribeTracks
音声対話Audio, DataAudio, Data
視覚入力を伴う音声対話Audio, Video, DataAudio, Data
モデルの準備前に入力が届かないよう、接続前に上りメディアを無効にします。 
engine.enableSendMediaStream(.audio, enable: false)
engine.enableSendMediaStream(.video, enable: false)
キャプチャ、トラック発行、送信許可は別々の操作です。送信を無効にしてもローカルのキャプチャは停止せず、Data イベントにも影響しません。送信を有効にしても、未追加のトラックが作成されるわけではありません。

4. 接続の確立

認証情報とトラック設定を AoqConnectConfig に設定し、次を呼び出します。 
engine.connect(connectConfig)
onConnectionStatusChange が .connected を返すのを待ってから、モデルの初期化に進みます。connect が戻っても、接続の成功を意味するわけではありません。

5. モデルイベントとメディアの交換

モデルイベントの送信と解析

クライアントは Data トラック経由でイベントを送信します。以下は iOS 向けの Swift コード例です。その他のインターフェイスは、iOS SDK リファレンスをご覧ください。 
// Build eventJSON according to the target model client event protocol.
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)
onDataMsg でレスポンスを解析します。このモデルは type フィールドでイベントの種類を識別します。フィールド、パラメーター、終了条件の詳細は、対象モデルのドキュメントに従ってください。

モデルの準備完了後にメディアを有効化

現在のモデル、セッション、タスクの準備完了条件を満たした後、設定済みの上り方向だけを有効にします。音声入力の場合は次を呼び出します。 
engine.enableSendMediaStream(.audio, enable: true)
動画入力が必要な場合にのみ .video を有効にします。 音声と映像はそれぞれのメディアトラックで、モデルイベントとテキストは Data トラックで送信します。たとえば AOQ 経由の Omni では、同じメディアを input_audio_buffer.append や input_image_buffer.append で再送する必要はありません。下り音声は設定済みプレーヤーまたは外部再生ロジックで処理します。

6. 対話の終了とリソースの解放

接続が不要になったら、アプリケーションから AOQ SDK の切断とリソース解放のインターフェイスを呼び出します。 
engine.disconnect()
AoqClientEngine.destroy()
予期しない切断後はアプリケーションの準備完了状態をクリアし、接続状態の管理に従ってください。再接続後はモデルを再初期化します。

Data チャネルでのイベントの送受信

クライアントは AOQ SDK の Data トラックでモデルイベントを送受信します。接続時には Data トラックの公開とサブスクライブの両方が必要です。送信時にはモデルイベントを AoqDataMsg にシリアライズし、各プラットフォームの Data 送信インターフェイスを呼び出します。受信時には onDataMsg コールバックでメッセージを解析します。詳細はプラットフォーム別 SDKをご覧ください。 送信するイベントの名前、フィールド、パラメーター、タイミングは、対象モデルのクライアントイベント定義に従います。受信後の解析、状態変化、結果、エラー処理は、モデルのサーバーイベント定義に従います。初期化イベントはモデルの要件に応じて送信し、その後のテキストイベントや制御イベントはアプリケーションの必要に応じて送信してください。
モデルまたはアプリケーションクライアントイベント（送信）サーバーイベント（受信）
Qwen-Omni-Realtimeクライアントイベントサーバーイベント
次のルールにも従ってください。
  • イベントの type フィールドでモデルイベントを識別し、関連する識別子はこのモデルのイベントリファレンスに従って処理します。
  • モデルが必要とする初期化の確認、入力のコミット、レスポンスのキャンセル、タスクの完了などの操作は、対応するプロトコルに従って Data チャネル内で処理します。これらはモデルの対話動作であり、トランスポート接続の切断とは別の操作です。
  • 終了前に、このモデルのイベントドキュメントに従って入力のコミットと結果の受信を完了してください。音声を最後まで再生する場合は、ローカルのキューに残った音声を処理してから接続を解放します。
  • 音声と動画のデータはメディアトラックで転送します。モデルのイベントドキュメントを参照する場合も、メディアのカプセル化と利用可能な対話モードは、ここで説明するアクセス方法に従います。WebSocket のメディア転送方式をそのまま適用しないでください。

高度な機能

機能用途ドキュメント
音声と映像の送信を個別制御モデルの準備完了待ち、上りメディアの一時停止、必要に応じた映像の有効化メディア送信の管理
音声デバイスと処理エンコード、デコード、スピーカー、ファイルミキシング、音声フレームのコールバック一般的な音声機能
外部音声入力アプリケーションが提供する音声ソースの使用カスタム音声キャプチャ
外部音声出力アプリケーションで出力音声を処理または再生カスタム音声再生
映像キャプチャと入力カメラまたはアプリケーションが提供する画像の使用一般的な映像機能, カスタム映像入力
メディア送信の制御はメディアのみに作用します。モデル応答のキャンセルやターンの送信には、対象モデルのイベントが引き続き必要です。

セッション設定の例

次の例は qwen3.8-omni-flash-realtime に適用されます。音声と動画はメディアトラックで転送し、WebSocket のメディア送信イベントは使用しません。
{
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Tina",
    "turn_detection": {
      "type": "server_vad"
    }
  }
}

AOQ SDK のダウンロード

以下のバージョン更新情報は、AOQ SDK の汎用機能を説明しています。このモデルのメディア対応範囲は、上記のこのモデルのメディア方向をご覧ください。
バージョンプラットフォームダウンロードリリース日リリースノート
v1.4.0AndroidAoqClientSdk-release.aarlibPluginOpus.zip2026-10-27
  1. 外部からの H.264 動画入力に対応しました。
  2. パフォーマンスが向上しました。
  3. 既知の安定性の問題を修正しました。
iOSAoqClientSdk.framework.zipAoqScreenShare.framework.zipPluginOpus.framework.zip
HarmonyOSAoqClientSdk.harlibPluginOpus.zip
WindowsAoqClientSdk-windows-x64.zip
macOSAoqClientSdk.framework.zipPluginOpus.framework.zip
Electronaoq-electron-sdk-1.4.0-59463182.tgznpm を使用してインストールすることもできます。npm install aoq-electron-sdk@1.4.0-59463182
Linuxx86_64: AoqClientSdk.ziparm64: AoqClientSdk.zip
v1.3.0Android2026-09-18

  1. 画面共有に対応。

  2. bitcode を非推奨化。

  3. .so ライブラリのリモート読み込みに対応。

  4. エンコードフレームの最大値を外部から設定可能に。

  5. デフォルトコーデックを Opus に変更。

  6. 性能を改善。

  7. 既知の安定性の問題を修正。

iOS
HarmonyOS
WindowsAoqClientSdk-windows-x64.zip
macOS
Electron
または npm でインストール： npm install aoq-electron-sdk@1.3.0-58586345
Linux
v1.2.2iOSAoqClientSdk.framework.zip2026-09-09

  1. システムまたはサードパーティーの音声通話による中断終了後、iOS の通話を再開できない問題を修正。

  2. iOS 通話開始時のエコーキャンセルを改善。

v1.2.0Android 2026-08-17

  1. macOS に対応

  2. Windows に対応

  3. Electron に対応

  4. Linux 用の Python と C++ API を追加

  5. 音量レベル検出を追加

  6. 性能を改善

  7. 既知の安定性の問題を修正

iOS
HarmonyOS
Windows
macOS
Electron
または npm でインストール: npm install aoq-electron-sdk@1.2.0-57407598
Linux
v1.1.0Android 2026-07-31

  1. ASR モデルに対応

  2. TTS モデルに対応

  3. マルチモーダル対話ツールキットに対応

  4. Linux プラットフォームに対応

  5. 性能を改善

  6. 既知の安定性の問題を修正

iOS
HarmonyOS
LinuxAoqClientSdk.zip
v1.0.1Android 2026-07-09

  1. AOQ プロトコルでモデルとアプリケーションにアクセス

  2. 音声と動画のコーデックパラメーター

  3. 音声・動画デバイスのキャプチャと再生

  4. カスタム外部音声キャプチャ

  5. カスタム外部動画キャプチャ

  6. カスタム外部動画エンコード

  7. メディアストリーム送信制御

iOS
HarmonyOS
AOQ は Opus コーデックを音声プラグインとして読み込みます。Opus のエンコードまたはデコードを使用するには、Opus プラグインをダウンロードしてプロジェクトに追加してください。

イベントリファレンス

シナリオ別チュートリアル