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

Qwen-Audio-Realtime AOQ アクセス

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

適用範囲

このドキュメントは 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 キーはサーバーにのみ保存してください。ブラウザーやモバイルアプリケーションに埋め込まないでください。

• マイクで音声をキャプチャする場合は、プラットフォームの要件に従ってマイクの権限を要求してください。

• SDK ダウンロードから、使用するプラットフォームの SDK をダウンロードしてください。

認証と接続認証情報

AppServer から次のリクエストを送信します。最初に API キーを環境変数として設定してください。ドメインの {WorkspaceId} をワークスペース ID に置き換えます。別のリージョンを使用する場合は、上記の対応するドメインを使用してください。clientIp は任意です。省略すると、ゲートウェイはリクエストの送信元 IP アドレスを使用します。

export ENDPOINT="{WorkspaceId}.cn-beijing.maas.aliyuncs.com"
curl -X POST \
  "https://${ENDPOINT}/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus" \
  -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>"}' に置き換えます。

リクエストのフィールド

レスポンスの例

{
    "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"}
}

レスポンスのフィールド

AOQ Client SDK の接続例

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)

JSONObject obj = new JSONObject(responseText);
AoqClientEngine.AoqConnectConfig cfg = new AoqClientEngine.AoqConnectConfig();
cfg.token = obj.optString("aoqTokenForClient", "");
cfg.sid = obj.optString("sid", "");
cfg.certFingerprint = obj.optString("clientRelayCertFingerprint", "");

JSONArray arr = obj.optJSONArray("clientRelayEndpoints");
if (arr != null) {
    for (int i = 0; i < arr.length(); i++) {
        JSONObject o = arr.optJSONObject(i);
        AoqClientEngine.AoqRelayEndpoint ep = new AoqClientEngine.AoqRelayEndpoint();
        // Fall back to the array index when route_index is missing
        ep.routeIndex = o.has("route_index") ? o.optInt("route_index", i) : i;
        ep.endpoint = o.optString("endpoint", "");
        ep.port = o.optInt("port", 0);
        cfg.relayEndpoints.add(ep);
    }
}

JSONObject ext = obj.optJSONObject("extraInfo");
cfg.workspaceIdHash = ext != null ? ext.optString("workspaceIdHash", "") : "";

AoqClientEngine.AoqTrackParam audio = new AoqClientEngine.AoqTrackParam();
audio.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
AoqClientEngine.AoqTrackParam data = new AoqClientEngine.AoqTrackParam();
data.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
cfg.publishTracks.add(audio);
cfg.publishTracks.add(data);
cfg.subscribeTracks.add(audio);
cfg.subscribeTracks.add(data);

engine.connect(cfg);

const obj = JSON.parse(responseText) as Record<string, Object | undefined>;
const cfg: AoqConnectConfig = {
    token: String(obj['aoqTokenForClient'] ?? ''),
    sid: String(obj['sid'] ?? ''),
    certFingerprint: String(obj['clientRelayCertFingerprint'] ?? ''),
    // Fall back to the array index when route_index is missing
    relayEndpoints: (obj['clientRelayEndpoints'] as Array<any>).map((item, index) => ({
        routeIndex: Number(item['route_index'] ?? index),
        endpoint: String(item['endpoint'] ?? ''),
        port: Number(item['port'] ?? 0)
    })),
    workspaceIdHash: String((obj['extraInfo'] as any)?.['workspaceIdHash'] ?? ''),
    publishTracks: [
        { trackType: AoqTrackType.AoqTrackTypeAudio },
        { trackType: AoqTrackType.AoqTrackTypeData }
    ],
    subscribeTracks: [
        { trackType: AoqTrackType.AoqTrackTypeAudio },
        { trackType: AoqTrackType.AoqTrackTypeData }
    ]
};
engine.connect(cfg);

処理フロー

1. AppServer 経由で接続認証情報を取得します。
2. SDK エンジンを作成し、コールバックを登録します。
3. メディアトラックと Data トラックを設定し、上りメディアの送信を無効にします。
4. AOQ 接続を開始し、接続完了を待ちます。
5. モデルのプロトコルに従って設定します。確認後、必要な上りメディアを有効にします。
6. 対話が終了したら切断し、リソースを解放します。

1. 接続認証情報の取得

クライアントは AppServer に認証情報を要求します。AppServer はこのモデルの Realtime 接続エンドポイントを呼び出し、ゲートウェイへのリクエストに API キーと x-dashscope-rtc-transport: moq を含めます。エンドポイント、リクエスト、フィールドの詳細は、Token 認証をご覧ください。

応答を AoqConnectConfig に対応付けます。

新しい接続ごとに新しい認証情報を取得してください。同じ接続でセッションを再利用したり、別のタスクを開始したりできるかどうかは、対象モデルのプロトコルに依存します。

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 の設定

メディア方向の選択

方向はクライアントを基準にしています。アプリケーションが必要とする入出力モダリティだけを設定し、使用しない方向のトラックは追加しないでください。

Data トラックは音声の方向とは独立しています。モデルイベントの送信には Data トラックを公開し、レスポンスの受信には Data トラックをサブスクライブします。テキストのみの入出力にも Data トラックが必要です。

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

次の表は、このモデルのメディア方向を示します。モデルの適用範囲は適用範囲をご覧ください。その他のアクセス方法は Qwen-Audio-Realtimeをご覧ください。

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

上り音声と下り音声を別々に設定します。上りには setAudioEncoderConfig、下りには setAudioDecoderConfig を使用します。これらはネットワーク転送を制御するパラメーターで、ゲートウェイがモデルに必要な形式に音声を変換します。転送時のエンコードは SDK の要件に、モデルイベント内の音声形式は対象モデルの要件に従って設定してください。

方向に応じて startAudioCapture または startAudioPlayer を開始します。カスタム入出力については、以下の高度な機能のセクションで説明します。

publishTracks はクライアントが送信するトラック、subscribeTracks はクライアントが受信するトラックです。

モデルの準備前に入力が届かないよう、接続前に上りメディアを無効にします。

engine.enableSendMediaStream(.audio, 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)

音声は Audio トラックで転送し、モデルイベントとテキストは Data トラックで転送します。input_audio_buffer.append で同じ音声を重複送信しないでください。下り音声は、設定したプレイヤーまたは外部再生ロジックが処理します。

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

接続が不要になったら、アプリケーションから AOQ SDK の切断とリソース解放のインターフェイスを呼び出します。

engine.disconnect()
AoqClientEngine.destroy()

予期しない切断後はアプリケーションの準備完了状態をクリアし、接続状態の管理に従ってください。再接続後はモデルを再初期化します。

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

クライアントは AOQ SDK の Data トラックでモデルイベントを送受信します。接続時には Data トラックの公開とサブスクライブの両方が必要です。送信時にはモデルイベントを AoqDataMsg にシリアライズし、各プラットフォームの Data 送信インターフェイスを呼び出します。受信時には onDataMsg コールバックでメッセージを解析します。詳細はプラットフォーム別 SDKをご覧ください。

送信するイベントの名前、フィールド、パラメーター、タイミングは、対象モデルのクライアントイベント定義に従います。受信後の解析、状態変化、結果、エラー処理は、モデルのサーバーイベント定義に従います。初期化イベントはモデルの要件に応じて送信し、その後のテキストイベントや制御イベントはアプリケーションの必要に応じて送信してください。

次のルールにも従ってください。

• イベントの type フィールドでモデルイベントを識別し、関連する識別子はこのモデルのイベントリファレンスに従って処理します。

• モデルが必要とする初期化の確認、入力のコミット、レスポンスのキャンセル、タスクの完了などの操作は、対応するプロトコルに従って Data チャネル内で処理します。これらはモデルの対話動作であり、トランスポート接続の切断とは別の操作です。

• 終了前に、このモデルのイベントドキュメントに従って入力のコミットと結果の受信を完了してください。音声を最後まで再生する場合は、ローカルのキューに残った音声を処理してから接続を解放します。

• 音声データはメディアトラックで転送します。モデルのイベントリファレンスを使用する場合、メディアのカプセル化と使用可能な対話モードはこのページに従ってください。WebSocket のメディア送信方法をそのまま適用しないでください。

高度な機能

AOQ SDK の汎用動画インターフェイスは、一般的な動画機能（汎用 SDK）とカスタム動画入力（汎用 SDK）をご覧ください。このモデルは動画の入出力をサポートしていません。

メディア送信の制御はメディアのみに作用します。モデル応答のキャンセルやターンの送信には、対象モデルのイベントが引き続き必要です。

セッション設定の例

{
  "type": "session.update",
  "session": {
    "voice": "longanqian_v3.1"
  }
}

AOQ SDK のダウンロード

以下のバージョン更新情報は、AOQ SDK の汎用機能を説明しています。このモデルのメディア対応範囲は、上記のこのモデルのメディア方向をご覧ください。

イベントリファレンス

• クライアントイベント
• サーバーイベント

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

• qwen-audio-3.1-realtime-plus を使用して AOQ 経由でリアルタイム音声対話を構築