Skip to main content

Akses AOQ Qwen-LiveTranslate-Realtime

Akses AOQ Qwen-LiveTranslate-Realtime

AOQ mengirim media dan peristiwa model pada track terpisah. SDK menangani perekaman, enkode/dekode, transmisi, dan pemutaran media. Aplikasi mengirim peristiwa model melalui track Data serta memproses respons. Halaman ini menggunakan arah media dan protokol peristiwa Qwen-LiveTranslate-Realtime.

Cakupan penggunaan

Dokumen ini ditujukan untuk seri Qwen-LiveTranslate-Realtime. Untuk daftar model, lihat Terjemahan audio dan video realtime. Contoh pada halaman ini menggunakan qwen3.8-livetranslate-flash-realtime. Konfigurasi dan bidang peristiwa untuk qwen3.5-livetranslate-flash-realtime berbeda. Untuk detailnya, lihat Peristiwa klien.
  • Gunakan API Key dan ID ruang kerja yang sesuai dengan wilayah dan ruang kerja yang dipilih.
  • Domain Beijing: {WorkspaceId}.cn-beijing.maas.aliyuncs.com; domain Singapura: {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com.
  • Simpan API Key hanya di server. Jangan sematkan dalam browser atau aplikasi seluler.
  • Saat mengambil audio melalui mikrofon, minta izin mikrofon sesuai persyaratan platform.
  • Unduh SDK untuk platform Anda dari Unduhan SDK.

Autentikasi dan kredensial koneksi

Untuk mengambil token lebih awal atau memahami seluruh alur otentikasi, lihat detail otentikasi koneksi.
Kirim permintaan berikut dari AppServer. Pertama, konfigurasikan API Key sebagai variabel lingkungan. Pilih wilayah pada URL permintaan di bawah ini, lalu masukkan ID ruang kerja Anda. clientIp bersifat opsional. Jika dihilangkan, gateway menggunakan alamat IP asal permintaan.
POSThttps://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-livetranslate-flash-realtime
POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-livetranslate-flash-realtime

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 '{}'
Untuk menentukan alamat IP publik klien, ganti -d '{}' dalam isi permintaan dengan -d '{"clientIp":"<CLIENT_PUBLIC_IP>"}'.

Bidang permintaan

Konfigurasi

Nilai

Deskripsi

endpoint

Pilih domain endpoint sesuai kasus penggunaan

Tentukan domain endpoint. Untuk detailnya, lihat Memilih wilayah, cakupan penerapan, dan endpoint. Jika menggunakan Token Plan, atur WorkspaceId dalam domain endpoint ke token-plan.

Content-Type

application/json

Jenis media pesan

Authorization

Bearer <YOUR_API_KEY>

API Key Anda

x-dashscope-rtc-transport

moq

Pilih protokol AOQ

clientIp

Alamat IP publik klien

Opsional. Jika dihilangkan, layanan menggunakan alamat IP asal permintaan yang diterima gateway. Jika ditentukan, layanan menggunakan clientIp. Layanan memilih endpoint Relay terbaik berdasarkan alamat IP klien.

Contoh respons

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

Bidang respons

Bidang

Deskripsi

sid

Identifier unik sesi.

aoqTokenForClient

Token koneksi klien. Teruskan nilai ini ke bidang token SDK.

clientRelayEndpoints

Array endpoint Relay. Setiap elemen dalam contoh respons berisi bidang berikut:
endpointAlamat endpoint Relay.portPort endpoint Relay.route_indexContoh iOS di bawah menggunakan indeks array jika bidang ini tidak ada.

clientRelayCertFingerprint

Sidik jari sertifikat TLS Relay.

sidExpiresInSecs

Masa berlaku sesi dalam detik.

extraInfo

Informasi tambahan.
workspaceIdHashHash ID ruang kerja.

Contoh koneksi AOQ Client SDK

clientIp adalah bidang opsional dalam badan permintaan. Jika tidak ditentukan, alamat IP yang mengirim permintaan ke gerbang Model Studio akan digunakan sebagai alamat IP klien. Jika ditentukan, nilai clientIp memiliki prioritas lebih tinggi. Pastikan AppServer bisnis Anda mendapatkan alamat IP asli klien dan meneruskannya agar mendapatkan titik akses Relay terbaik.
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)

Alur kerja

AOQ Diagram urutan koneksi
  1. Dapatkan kredensial koneksi melalui AppServer.
  2. Buat mesin SDK dan daftarkan callback.
  3. Atur trek media dan Data, lalu nonaktifkan pengiriman media upstream.
  4. Buat koneksi AOQ dan tunggu hingga tersambung.
  5. Konfigurasikan model sesuai protokolnya. Setelah dikonfirmasi, aktifkan media upstream yang diperlukan.
  6. Putuskan koneksi dan lepas sumber daya setelah interaksi selesai.
  • Data media ditangani oleh AOQ SDK, yang bertanggung jawab atas perekaman, pemrosesan, pengiriman, penerimaan, dan pemutaran media. Data harus dikirim serta diterima oleh pemanggil sesuai definisi peristiwa model tujuan.
  • Koneksi yang berhasil menunjukkan bahwa saluran transmisi dengan model telah terbentuk. Klien hanya boleh mengaktifkan media uplink yang diperlukan setelah inisialisasi model selesai. Untuk model contoh qwen3.8-livetranslate-flash-realtime pada halaman ini, setelah mengirim session.update, tunggu session.updated sebelum mengaktifkan transmisi media.

1. Memperoleh kredensial koneksi

Klien meminta kredensial dari AppServer. AppServer memanggil endpoint koneksi Realtime model ini dan menyertakan API Key serta x-dashscope-rtc-transport: moq dalam permintaan gateway. Untuk endpoint, permintaan, dan deskripsi bidang lengkap, lihat Autentikasi token. Petakan respons ke AoqConnectConfig:
Respons gatewayKonfigurasi SDK
aoqTokenForClienttoken
sidsid
clientRelayCertFingerprintcertFingerprint
clientRelayEndpointsrelayEndpoints, konversi setiap titik akses sesuai struktur
extraInfo contains workspaceIdHashworkspaceIdHash
Dapatkan kredensial baru untuk setiap koneksi baru. Penggunaan ulang sesi atau memulai tugas lain pada koneksi yang sama bergantung pada protokol model tujuan.

2. Menginisialisasi SDK dan mendaftarkan callback

Buat mesin dan daftarkan callback untuk status koneksi, pesan Data, dan kesalahan. Contoh berikut menggunakan Swift di iOS:
let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)
Implementasikan AoqEngineDelegate; kelola status koneksi dalam onConnectionStatusChange, uraikan peristiwa model target dalam onDataMsg, dan tangani kesalahan SDK dalam onError. Peristiwa kesalahan yang dikembalikan model juga harus ditangani secara terpisah dalam logika pemrosesan pesan Data. Untuk detail antarmuka SDK dan kesalahan, lihat SDK per platform dan Referensi fitur.

3. Mengonfigurasi SDK

Memilih arah media

Arah dilihat dari sisi klien. Konfigurasikan hanya modalitas input dan output yang diperlukan aplikasi. Jangan tambahkan track untuk arah yang tidak digunakan.
ArahKonfigurasiPenggunaan umum
Kirim audio: Publikasikan track Audio, atur encoder audio, konfigurasikan perekaman bawaan atau eksternal Terjemahan suara
Terima audio: Berlangganan track Audio, atur decoder audio, konfigurasikan pemutar atau pemutaran eksternalMenerjemahkan dan memutar audio
Kirim video: Konfigurasikan track Video, kamera, atau input video eksternal sesuai versi pilihan dan skenario yang didukungMengirim video ke model yang mendukung input visual
Menerima video:Model ini tidak mendukung output videoJangan konfigurasikan langganan video
Track Data independen dari track media. Publikasikan track Data untuk mengirim peristiwa model dan berlangganan track Data untuk menerima respons. Teks terjemahan dikembalikan melalui track Data.

Arah media untuk model ini

Tabel berikut mencantumkan arah media untuk model ini. Untuk cakupan model, lihat Cakupan penerapan. Metode integrasi lain dijelaskan dalam Qwen-LiveTranslate-Realtime.
Model atau aplikasiMengirim audioMenerima audioMengirim videoMenerima video
Qwen-LiveTranslate-Realtime Aktifkan saat input suara digunakanAktifkan jika terjemahan suara diperlukanKonfigurasikan sesuai versi dan skenario pilihanTidak mendukung pengaktifan

Mengatur parameter dan trek media

Atur audio upstream dan downstream secara terpisah: gunakan setAudioEncoderConfig untuk upstream dan setAudioDecoderConfig untuk downstream. Parameter ini mengendalikan transmisi jaringan; gateway mengonversi audio ke format yang diperlukan model. Atur encoding transport dan format audio dalam peristiwa model masing-masing sesuai persyaratan SDK dan model tujuan. Mulai startAudioCapture atau startAudioPlayer sesuai arahnya. Input dan output kustom dijelaskan pada bagian kemampuan lanjutan di bawah. publishTracks dikirim oleh klien, sedangkan subscribeTracks diterima oleh klien:
SkenariopublishTrackssubscribeTracks
Terjemahan suara Audio, Data Audio, Data
Nonaktifkan media upstream sebelum terhubung agar input tidak sampai ke model sebelum model siap:
engine.enableSendMediaStream(.audio, enable: false)
Pengambilan, publikasi trek, dan izin pengiriman merupakan operasi terpisah. Menonaktifkan transmisi tidak menghentikan pengambilan lokal atau memengaruhi peristiwa Data. Mengaktifkan transmisi tidak membuat trek yang belum ditambahkan.

4. Membuat koneksi

Isi kredensial dan konfigurasi track dalam AoqConnectConfig, lalu panggil:
engine.connect(connectConfig)
Tunggu onConnectionStatusChange mengembalikan .connected, lalu lanjutkan ke inisialisasi model. Kembalinya connect tidak berarti koneksi telah berhasil.

5. Bertukar peristiwa model dan media

Mengirim dan menguraikan peristiwa model

Klien mengirim peristiwa melalui track Data. Berikut cuplikan kode Swift untuk iOS; untuk antarmuka lain, lihat Referensi SDK iOS.
// Build eventJSON according to the target model client event protocol.
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)
Uraikan respons dalam onDataMsg. Model ini mengidentifikasi jenis peristiwa melalui bidang type. Ikuti dokumentasi model target untuk bidang, parameter, dan kondisi penghentian lengkap.

Mengaktifkan media setelah model siap

Setelah model, sesi, atau tugas saat ini memenuhi kondisi kesiapan, aktifkan hanya arah upstream yang telah dikonfigurasi. Untuk input ucapan, panggil:
engine.enableSendMediaStream(.audio, enable: true)
Audio dikirim melalui track Audio; peristiwa model dan teks dikirim melalui track Data. Jangan gunakan input_audio_buffer.append untuk mengirim audio yang sama berulang kali. Audio downstream diproses oleh pemutar yang dikonfigurasi atau logika pemutaran eksternal.

6. Mengakhiri interaksi dan melepas sumber daya

Urutan penutupan berikut berlaku untuk terjemahan suara AOQ qwen3.8-livetranslate-flash-realtime:
  1. Hentikan perekaman dan nonaktifkan audio uplink. Hentikan pengiriman input, lalu kirim satu pesan session.finish melalui track Data.
  2. Pertahankan koneksi AOQ, langganan Data, dan pemutaran audio. Terus terima teks asli, terjemahan, serta audio terjemahan untuk kalimat terakhir, lalu tunggu session.finished.
  3. Jika audio terjemahan harus diputar hingga selesai, putuskan koneksi dan lepas sumber daya hanya setelah menyelesaikan pemutaran serta pembersihan audio lokal.
Untuk deskripsi session.finish dan session.finished, lihat Peristiwa klien dan Peristiwa server. Untuk kode lengkap, lihat Praktik terjemahan suara realtime. Setelah menyelesaikan langkah penutupan di atas, lapisan bisnis klien memanggil antarmuka pemutusan koneksi dan pelepasan sumber daya AOQ serta SDK:
engine.disconnect()
AoqClientEngine.destroy()
Setelah koneksi terputus secara tidak terduga, hapus status kesiapan aplikasi dan ikuti Pengelolaan status koneksi. Inisialisasi kembali model setelah terhubung ulang.

Mengirim dan menerima peristiwa melalui saluran Data

Klien mengirim dan menerima peristiwa model melalui track Data AOQ SDK. Saat terhubung, publikasi dan langganan track Data sama-sama diperlukan. Saat mengirim, serialisasikan peristiwa model ke AoqDataMsg dan panggil antarmuka pengiriman Data platform. Saat menerima, uraikan pesan dalam callback onDataMsg. Lihat SDK per platform untuk detail antarmuka. Nama, bidang, parameter, dan waktu pengiriman peristiwa mengikuti Definisi peristiwa klien model target. Penguraian, perubahan status, hasil, dan penanganan kesalahan setelah menerima pesan mengikuti Definisi peristiwa server model. Kirim peristiwa inisialisasi sesuai persyaratan model; kirim peristiwa teks dan kontrol berikutnya sesuai kebutuhan aplikasi.
Model atau aplikasiPeristiwa klien (kirim)Peristiwa server (terima)
Qwen-LiveTranslate-RealtimePeristiwa klienPeristiwa server
Ikuti juga aturan berikut:
  • Gunakan bidang type peristiwa untuk mengidentifikasi peristiwa model, dan tangani pengenal terkait sesuai referensi peristiwa model ini.
  • Operasi yang diperlukan model, seperti konfirmasi inisialisasi, pengiriman input, pembatalan respons, dan penyelesaian tugas, ditangani dalam saluran Data sesuai protokolnya. Operasi ini merupakan semantik interaksi model dan berbeda dari pemutusan koneksi transport.
  • Sebelum mengakhiri, selesaikan pengiriman input dan penerimaan hasil sesuai dokumentasi peristiwa model ini. Jika pemutaran lengkap diperlukan, lepaskan koneksi hanya setelah memproses audio yang masih mengantre secara lokal.
  • Data media dikirim melalui track media. Saat merujuk dokumentasi peristiwa model, enkapsulasi media dan mode interaksi yang tersedia tetap mengikuti metode akses pada dokumen ini, bukan langsung menggunakan cara transmisi media WebSocket.

Fitur lanjutan

KemampuanKasus penggunaanDokumentasi
Mengontrol transmisi audioMenunggu kesiapan model, menjeda audio uplinkManajemen transmisi aliran media
Perangkat dan pemrosesan audioEnkode/dekode, speaker, pencampuran file, callback frame audioFungsi audio umum
input audio eksternalMenggunakan sumber audio sisi klienPerekaman audio khusus
output audio eksternalDiproses atau diputar oleh sisi klienPemutaran audio khusus
Untuk antarmuka video umum AOQ dan SDK, lihat Fitur video umum dan Input video khusus. Kontrol transmisi hanya memengaruhi media. Pembatalan respons model dan pengiriman giliran tetap memerlukan peristiwa model tujuan.

Contoh konfigurasi sesi

Contoh berikut berlaku untuk qwen3.8-livetranslate-flash-realtime. Audio dikirim melalui track media dan tidak menggunakan peristiwa transmisi media WebSocket.
Contoh berikut menerjemahkan ucapan ke bahasa Inggris menggunakan suara default tanpa mengaktifkan kloning suara. Untuk kode lengkap, lihat Praktik terjemahan suara realtime.
{
  "type": "session.update",
  "session": {
    "output_modalities": [
      "text",
      "audio"
    ],
    "audio": {
      "input": {
        "turn_detection": {
          "type": "speaker_detection",
          "threshold": 0.5
        }
      }
    },
    "translation": {
      "language": "en"
    }
  }
}

Unduhan AOQ SDK

Catatan pembaruan versi di bawah menjelaskan kemampuan umum AOQ SDK. Cakupan dukungan media model ini dijelaskan pada Arah media untuk model ini di atas.
VersiPlatformUnduhanTanggal rilisCatatan rilis
v1.4.0AndroidAoqClientSdk-release.aarlibPluginOpus.zip2026-10-27
  1. Menambahkan dukungan untuk video H.264 yang dimasukkan dari sumber eksternal.
  2. Performa yang ditingkatkan.
  3. Memperbaiki masalah stabilitas yang diketahui.
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.tgzAtau, instal melalui npm:npm install aoq-electron-sdk@1.4.0-59463182
Linuxx86_64: AoqClientSdk.ziparm64: AoqClientSdk.zip
v1.3.0Android2026-09-18
  1. Menambahkan dukungan berbagi layar.

  2. Menghentikan penggunaan bitcode.

  3. Menambahkan dukungan pemuatan pustaka .so dari jarak jauh.

  4. Menambahkan dukungan pengaturan eksternal nilai maksimum frame yang dienkode.

  5. Mengubah codec default menjadi Opus.

  6. Meningkatkan kinerja.

  7. Memperbaiki masalah stabilitas yang diketahui.

iOS
HarmonyOS
WindowsAoqClientSdk-windows-x64.zip
macOS
Electron
Atau instal dengan npm: npm install aoq-electron-sdk@1.3.0-58586345
Linux
v1.2.2iOSAoqClientSdk.framework.zip2026-09-09
  1. Memperbaiki masalah panggilan iOS yang tidak dapat dilanjutkan setelah interupsi sistem atau panggilan suara pihak ketiga berakhir.

  2. Meningkatkan pembatalan gema pada awal panggilan iOS.

v1.2.0Android 2026-08-17
  1. Menambahkan dukungan macOS

  2. Menambahkan dukungan Windows

  3. Menambahkan dukungan Electron

  4. Menambahkan API Python dan C++ untuk Linux

  5. Menambahkan deteksi tingkat volume

  6. Meningkatkan kinerja

  7. Memperbaiki masalah stabilitas yang diketahui

iOS
HarmonyOS
Windows
macOS
Electron
Atau, instal menggunakan npm: npm install aoq-electron-sdk@1.2.0-57407598
Linux
v1.1.0Android 2026-07-31
  1. Mendukung model ASR

  2. Mendukung model TTS

  3. Mendukung toolkit interaksi multimodal

  4. Menambahkan dukungan platform Linux

  5. Meningkatkan kinerja

  6. Memperbaiki masalah stabilitas yang diketahui

iOS
HarmonyOS
LinuxAoqClientSdk.zip
v1.0.1Android 2026-07-09
  1. Akses ke model dan aplikasi melalui protokol AOQ

  2. Parameter codec audio dan video

  3. Perekaman dan pemutaran perangkat audio serta video

  4. Perekaman audio eksternal khusus

  5. Perekaman video eksternal khusus

  6. Enkode video eksternal khusus

  7. Kontrol pengiriman aliran media

iOS
HarmonyOS
AOQ memuat codec Opus sebagai plugin audio. Untuk menggunakan encoding atau decoding Opus, unduh plugin Opus dan tambahkan ke proyek.

Referensi event

Tutorial skenario