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

Qwen-LiveTranslate-Realtime AOQ アクセス

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

適用範囲

このドキュメントは Qwen-LiveTranslate-Realtime シリーズを対象とします。モデル一覧は、リアルタイム音声・動画翻訳をご覧ください。このページのサンプルは qwen3.8-livetranslate-flash-realtime を使用します。qwen3.5-livetranslate-flash-realtime では設定とイベントフィールドが異なります。詳細は、クライアントイベントをご覧ください。

• 選択したリージョンとワークスペースに対応する 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=qwen3.8-livetranslate-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>"}' に置き換えます。

リクエストのフィールド

レスポンスの例

{
    "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-LiveTranslate-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. 対話の終了とリソースの解放

次の終了手順は、qwen3.8-livetranslate-flash-realtime の AOQ 音声翻訳に適用されます。

1. キャプチャを停止して上り音声を無効にします。入力の送信を終了し、Data トラックで session.finish メッセージを 1 回送信します。
2. AOQ 接続、Data の購読、音声再生を維持し、最後の文の原文、訳文、翻訳音声を引き続き受信して、session.finished を待ちます。
3. 翻訳音声を最後まで再生する必要がある場合は、ローカルでの音声再生の後処理を完了してから、接続を切断してリソースを解放します。

session.finish と session.finished の説明は、それぞれクライアントイベントとサーバーイベントをご覧ください。完全なコードは、リアルタイム音声翻訳の実践をご覧ください。

上記の終了処理を完了したら、クライアントの業務レイヤーが AOQ と SDK の切断およびリソース解放インターフェイスを呼び出します。

engine.disconnect()
AoqClientEngine.destroy()

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

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

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

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

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

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

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

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

• メディアデータはメディアトラックで転送します。モデルのイベントドキュメントを参照する場合も、メディアのカプセル化と利用可能な対話モードは、このドキュメントのアクセス方法に従います。WebSocket のメディア転送方式をそのまま適用しないでください。

高度な機能

AOQ と SDK の汎用動画インターフェイスは、共通動画機能とカスタム動画入力をご覧ください。

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

セッション設定の例

次の例は、デフォルト音声を使用し、音声クローニングを有効にせずに発話を英語に翻訳します。完全なコードは、リアルタイム音声翻訳の実践をご覧ください。

{
  "type": "session.update",
  "session": {
    "output_modalities": [
      "text",
      "audio"
    ],
    "audio": {
      "input": {
        "turn_detection": {
          "type": "speaker_detection",
          "threshold": 0.5
        }
      }
    },
    "translation": {
      "language": "en"
    }
  }
}

AOQ SDK のダウンロード

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

イベントリファレンス

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

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

• AOQ で qwen3.8-livetranslate-flash-realtime にアクセスしてリアルタイム音声翻訳を実現