TL;DR
Qwen3.5-Omni menerima teks, gambar, audio, dan video sebagai masukan dan mengembalikan teks atau ucapan waktu nyata. Akses melalui Alibaba Cloud DashScope API atau jalankan secara lokal melalui HuggingFace Transformers. Panduan ini mencakup penyiapan API, contoh kode yang berfungsi untuk setiap modalitas, kloning suara, dan cara menguji permintaan Anda dengan Apidog.
Yang Sedang Anda Gunakan
Qwen3.5-Omni adalah model tunggal yang menangani empat jenis masukan secara bersamaan: teks, gambar, audio, dan video. Ini mengembalikan teks atau ucapan alami, tergantung pada bagaimana Anda mengonfigurasi permintaan.
Dirilis 30 Maret 2026, ini dibangun di atas arsitektur Thinker-Talker dengan inti MoE. Thinker memproses masukan multimodal dan bernalar di atasnya. Talker mengonversi keluaran menjadi ucapan menggunakan sistem multi-codebook yang memulai streaming audio sebelum respons lengkap selesai.
Tiga varian tersedia:
- Plus: Kualitas tertinggi, terbaik untuk penalaran dan kloning suara
- Flash: Kecepatan dan kualitas seimbang, direkomendasikan untuk sebagian besar penggunaan produksi
- Light: Latensi terendah, untuk skenario seluler dan edge
Panduan ini menggunakan Flash untuk sebagian besar contoh karena ini adalah titik awal yang tepat untuk sebagian besar aplikasi. Ganti dengan Plus di mana Anda membutuhkan kualitas maksimum.
Akses API melalui DashScope
DashScope API dari Alibaba Cloud adalah cara utama untuk menggunakan Qwen3.5-Omni dalam produksi. Anda memerlukan akun DashScope dan kunci API.
Langkah 1: Buat akun DashScope
Kunjungi dashscope.aliyuncs.com dan daftar. Jika Anda sudah memiliki akun Alibaba Cloud, gunakan itu.
Langkah 2: Dapatkan kunci API Anda
- Masuk ke konsol DashScope
- Klik Manajemen Kunci API di bilah sisi kiri
- Klik Buat Kunci API
- Salin kuncinya (format:
sk-...)
Langkah 3: Instal SDK
pip install dashscope
Atau gunakan titik akhir yang kompatibel dengan OpenAI secara langsung dengan SDK openai:
pip install openai
DashScope mengekspos API yang kompatibel dengan OpenAI di https://dashscope.aliyuncs.com/compatible-mode/v1, yang berarti Anda dapat menukar base_url Anda dan menggunakan kode yang sama dengan yang akan Anda tulis untuk OpenAI.
Masukan dan Keluaran Teks
Mulailah dengan kasus paling sederhana: teks masuk, teks keluar.
from openai import OpenAI
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
)
response = client.chat.completions.create(
model="qwen3.5-omni-flash",
messages=[
{
"role": "user",
"content": "Explain the difference between REST and GraphQL APIs in plain terms."
}
],
)
print(response.choices[0].message.content)
Beralihlah ke qwen3.5-omni-plus untuk tugas penalaran yang lebih sulit atau qwen3.5-omni-light ketika latensi menjadi prioritas.
Masukan audio: transkripsi dan pemahaman
Berikan URL file audio atau audio yang dikodekan base64. Model ini mentranskripsi, memahami, dan bernalar atas konten secara bawaan. Tidak diperlukan langkah ASR terpisah.
import base64
from openai import OpenAI
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
)
# Load a local audio file
with open("meeting_recording.wav", "rb") as f:
audio_data = base64.b64encode(f.read()).decode("utf-8")
response = client.chat.completions.create(
model="qwen3.5-omni-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "input_audio",
"input_audio": {
"data": audio_data,
"format": "wav"
}
},
{
"type": "text",
"text": "Summarize the key decisions made in this meeting and list any action items."
}
]
}
],
)
print(response.choices[0].message.content)
Model ini menangani 113 bahasa untuk pengenalan suara. Anda tidak perlu menentukan bahasa; ia mendeteksinya secara otomatis.
Format audio yang didukung: WAV, MP3, M4A, OGG, FLAC.
Keluaran audio: text-to-speech dalam respons
Untuk mendapatkan ucapan alih-alih teks, atur parameter modalities dan konfigurasikan keluaran audio:
from openai import OpenAI
import base64
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
)
response = client.chat.completions.create(
model="qwen3.5-omni-flash",
modalities=["text", "audio"],
audio={"voice": "Chelsie", "format": "wav"},
messages=[
{
"role": "user",
"content": "Describe the steps to authenticate a REST API using OAuth 2.0."
}
],
)
# The response includes both text and audio
text_content = response.choices[0].message.content
audio_data = response.choices[0].message.audio.data # base64-encoded WAV
# Save the audio
with open("response.wav", "wb") as f:
f.write(base64.b64decode(audio_data))
print(f"Text: {text_content}")
print("Audio saved to response.wav")
Dua suara bawaan tersedia: Chelsie (perempuan) dan Ethan (laki-laki). Pembentukan ucapan berfungsi dalam 36 bahasa.
Masukan gambar: pemahaman visual
Berikan URL gambar atau gambar yang dikodekan base64 bersama dengan pertanyaan teks:
from openai import OpenAI
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
)
response = client.chat.completions.create(
model="qwen3.5-omni-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/api-diagram.png"
}
},
{
"type": "text",
"text": "Describe this API architecture diagram and identify any potential bottlenecks."
}
]
}
],
)
print(response.choices[0].message.content)
Untuk gambar lokal, kodekan sebagai base64:
import base64
with open("screenshot.png", "rb") as f:
image_data = base64.b64encode(f.read()).decode("utf-8")
# Use data URL format
image_url = f"data:image/png;base64,{image_data}"
response = client.chat.completions.create(
model="qwen3.5-omni-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {"url": image_url}
},
{
"type": "text",
"text": "What error is shown in this screenshot?"
}
]
}
],
)
Masukan video: memahami rekaman dan tangkapan layar
Masukan video adalah tempat Qwen3.5-Omni melakukan sesuatu yang tidak bisa dilakukan oleh model teks atau gambar: bernalar di seluruh trek visual dan audio secara bersamaan.
from openai import OpenAI
import base64
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
)
# Pass a video URL
response = client.chat.completions.create(
model="qwen3.5-omni-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "video_url",
"video_url": {
"url": "https://example.com/product-demo.mp4"
}
},
{
"type": "text",
"text": "Describe what the developer is building in this demo and write equivalent code."
}
]
}
],
)
print(response.choices[0].message.content)
Pengkodean Vibe Audio-Visual
Kasus penggunaan "Vibe Coding" adalah meneruskan rekaman layar dan meminta model untuk menghasilkan kode dari apa yang dilihatnya:
with open("screen_recording.mp4", "rb") as f:
video_data = base64.b64encode(f.read()).decode("utf-8")
response = client.chat.completions.create(
model="qwen3.5-omni-plus", # Use Plus for best code generation quality
messages=[
{
"role": "user",
"content": [
{
"type": "video_url",
"video_url": {
"url": f"data:video/mp4;base64,{video_data}"
}
},
{
"type": "text",
"text": "Watch this screen recording and write the complete code that replicates what you see being built. Include all the UI components and their interactions."
}
]
}
],
)
print(response.choices[0].message.content)
Jendela konteks 256K token dapat memuat sekitar 400 detik video 720p dengan audio. Untuk rekaman yang lebih panjang dari itu, pangkas atau pisahkan.
Kloning suara
Kloning suara memungkinkan Anda memberikan suara target kepada model dan membuatnya merespons dengan suara tersebut. Ini tersedia di Plus dan Flash melalui API.
import base64
from openai import OpenAI
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
)
# Load a 10-30 second voice sample for cloning
with open("voice_sample.wav", "rb") as f:
voice_sample = base64.b64encode(f.read()).decode("utf-8")
response = client.chat.completions.create(
model="qwen3.5-omni-plus",
modalities=["text", "audio"],
audio={
"voice": "custom",
"format": "wav",
"voice_sample": {
"data": voice_sample,
"format": "wav"
}
},
messages=[
{
"role": "user",
"content": "Welcome to the Apidog developer portal. How can I help you today?"
}
],
)
audio_data = response.choices[0].message.audio.data
with open("cloned_response.wav", "wb") as f:
f.write(base64.b64decode(audio_data))
Tips untuk kualitas kloning suara:
- Gunakan rekaman bersih tanpa kebisingan latar belakang
- 15-30 detik bekerja lebih baik daripada klip yang sangat pendek
- Format WAV pada 16kHz atau lebih tinggi
- Sampel suara harus memiliki ucapan alami, bukan teks yang dibaca keras, untuk pencocokan prosodi yang lebih baik
Respons streaming
Untuk obrolan suara waktu nyata atau aplikasi interaktif, gunakan streaming. Model mulai mengembalikan audio sebelum respons lengkap dihasilkan:
from openai import OpenAI
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
)
stream = client.chat.completions.create(
model="qwen3.5-omni-flash",
modalities=["text", "audio"],
audio={"voice": "Ethan", "format": "pcm16"},
messages=[
{
"role": "user",
"content": "Explain how WebSocket connections differ from HTTP polling."
}
],
stream=True,
)
audio_chunks = []
text_chunks = []
for chunk in stream:
delta = chunk.choices[0].delta
if hasattr(delta, "audio") and delta.audio:
if delta.audio.get("data"):
audio_chunks.append(delta.audio["data"])
if delta.content:
text_chunks.append(delta.content)
print(delta.content, end="", flush=True)
print() # newline after streaming text
# Combine and save audio chunks
if audio_chunks:
import base64
full_audio = b"".join(base64.b64decode(chunk) for chunk in audio_chunks)
with open("streamed_response.pcm", "wb") as f:
f.write(full_audio)
Format PCM16 bekerja dengan baik untuk streaming karena Anda dapat menyalurkannya langsung ke buffer keluaran audio tanpa menunggu file lengkap.
Percakapan multi-giliran dengan modalitas campuran
Percakapan nyata mencampur masukan di berbagai giliran. Berikut cara mengelola riwayat percakapan dengan modalitas yang berbeda:
from openai import OpenAI
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
)
conversation = []
def send_message(content_parts):
conversation.append({"role": "user", "content": content_parts})
response = client.chat.completions.create(
model="qwen3.5-omni-flash",
messages=conversation,
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
return reply
# Turn 1: text
print(send_message([{"type": "text", "text": "I have an API that keeps returning 503 errors."}]))
# Turn 2: add an image (error log screenshot)
import base64
with open("error_log.png", "rb") as f:
img = base64.b64encode(f.read()).decode()
print(send_message([
{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img}"}},
{"type": "text", "text": "Here's the error log screenshot. What's causing this?"}
]))
# Turn 3: follow-up text
print(send_message([{"type": "text", "text": "How do I fix the connection pool exhaustion you mentioned?"}]))
Jendela konteks 256K berarti Anda dapat melakukan percakapan panjang, termasuk yang berisi gambar dan audio tersemat, tanpa mengalami masalah pemotongan.
Penyebaran lokal dengan HuggingFace
Jika Anda perlu menjalankan Qwen3.5-Omni pada infrastruktur Anda sendiri:
pip install transformers==4.57.3
pip install accelerate
pip install qwen-omni-utils -U
pip install -U flash-attn --no-build-isolation
import soundfile as sf
from transformers import Qwen3OmniMoeForConditionalGeneration, Qwen3OmniMoeProcessor
from qwen_omni_utils import process_mm_info
model_path = "Qwen/Qwen3-Omni-30B-A3B-Instruct"
model = Qwen3OmniMoeForConditionalGeneration.from_pretrained(
model_path,
device_map="auto",
attn_implementation="flash_attention_2",
)
processor = Qwen3OmniMoeProcessor.from_pretrained(model_path)
conversation = [
{
"role": "system",
"content": [
{"type": "text", "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."}
],
},
{
"role": "user",
"content": [
{"type": "audio", "audio": "path/to/your/audio.wav"},
{"type": "text", "text": "What is being discussed in this audio?"}
],
},
]
text = processor.apply_chat_template(
conversation,
add_generation_prompt=True,
tokenize=False,
)
audios, images, videos = process_mm_info(conversation, use_audio_in_video=True)
inputs = processor(
text=text,
audio=audios,
images=images,
videos=videos,
return_tensors="pt",
padding=True,
)
inputs = inputs.to(model.device).to(model.dtype)
text_ids, audio_output = model.generate(**inputs, speaker="Chelsie")
text_response = processor.batch_decode(text_ids, skip_special_tokens=True)[0]
sf.write("local_response.wav", audio_output.reshape(-1).cpu().numpy(), samplerate=24000)
print(text_response)
Persyaratan memori GPU untuk penyebaran lokal:
| Varian | Presisi | Min VRAM |
|---|---|---|
| Plus (30B MoE) | BF16 | ~40GB |
| Flash | BF16 | ~20GB |
| Light | BF16 | ~10GB |
Untuk inferensi lokal produksi, gunakan vLLM alih-alih HuggingFace Transformers. Model MoE berjalan lebih cepat di bawah optimisasi perutean vLLM.
Menguji permintaan Qwen3.5-Omni Anda dengan Apidog
Permintaan API multimodal lebih sulit untuk di-debug daripada JSON biasa. Anda berurusan dengan audio dan video yang dikodekan base64, array konten bersarang, dan respons yang dapat mencakup teks dan audio. Melakukan ini dari terminal akan cepat membosankan.
Apidog menanganinya dengan rapi. Siapkan titik akhir DashScope Anda sebagai koleksi baru, simpan kunci API Anda sebagai variabel lingkungan, dan bangun template permintaan untuk setiap modalitas yang sedang Anda kerjakan.
Untuk setiap varian (Plus, Flash, Light), Anda dapat menduplikasi permintaan dasar dan mengubah parameter model. Jalankan ketiganya secara berurutan dan bandingkan respons, latensi, serta kualitas keluaran dalam satu tampilan.
Anda juga dapat menulis pernyataan pengujian di Apidog untuk memverifikasi respons multimodal Anda:
- Periksa apakah
choices[0].message.contenttidak kosong untuk respons teks - Verifikasi bahwa
choices[0].message.audio.dataada saat keluaran audio diminta - Pastikan latensi respons untuk Flash berada di bawah ambang batas target Anda
Ini berguna ketika Anda memutuskan varian mana yang akan digunakan dalam produksi.
Penanganan kesalahan dan logika coba lagi
Batas laju dan batas waktu umum terjadi pada model multimodal besar, terutama untuk masukan video. Bangun penanganan coba lagi sejak awal:
import time
import random
from openai import OpenAI, RateLimitError, APITimeoutError, APIConnectionError
client = OpenAI(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key="sk-YOUR_DASHSCOPE_KEY",
timeout=120, # 2-minute timeout for large video inputs
)
def call_with_retry(messages, model="qwen3.5-omni-flash", max_retries=3):
for attempt in range(max_retries):
try:
return client.chat.completions.create(
model=model,
messages=messages,
)
except RateLimitError:
wait = (2 ** attempt) + random.uniform(0, 1)
print(f"Rate limit hit. Waiting {wait:.1f}s...")
time.sleep(wait)
except (APITimeoutError, APIConnectionError) as e:
if attempt == max_retries - 1:
raise
wait = (2 ** attempt) + random.uniform(0, 1)
print(f"Connection error: {e}. Retrying in {wait:.1f}s...")
time.sleep(wait)
raise RuntimeError(f"Failed after {max_retries} attempts")
Untuk masukan video yang lebih besar dari 100MB, pertimbangkan:
- Memotong ke bagian yang relevan sebelum mengirim
- Mengurangi resolusi ke 480p jika konten visual tidak memerlukan resolusi tinggi
- Membagi rekaman panjang menjadi segmen dan mengumpulkan hasilnya
Masalah umum dan perbaikan
“Keluaran audio terdistorsi pada angka atau istilah teknis”Ini adalah masalah yang diatasi oleh teknologi ARIA. Pastikan Anda menggunakan Qwen3.5-Omni (bukan versi sebelumnya). Jika Anda melakukan self-hosting, gunakan bobot model terbaru dari HuggingFace.
“Model terus berbicara saat saya mengirimkan interupsi audio”Interupsi semantik memerlukan varian Flash atau Plus. Varian Light mungkin tidak memiliki fitur ini. Juga periksa bahwa Anda melakukan streaming respons (bukan batch) agar interupsi berfungsi.
“Kualitas kloning suara buruk”Sampel suara harus bersih. Hapus kebisingan latar belakang dengan alat seperti Audacity sebelum mengunggah. Gunakan setidaknya 15 detik audio. WAV pada 16kHz atau 44.1kHz bekerja paling baik.
“Masukan video mengembalikan kesalahan tentang batas token”256K token mencakup sekitar 400 detik video 720p. Video yang lebih panjang memerlukan pemotongan atau resolusi lebih rendah. Periksa durasi video Anda dan kurangi hingga di bawah 6 menit untuk keamanan.
“Penyebaran lokal sangat lambat”Gunakan vLLM, bukan HuggingFace Transformers, untuk inferensi lokal produksi. Model MoE membutuhkan optimisasi perutean vLLM untuk throughput yang wajar.
FAQ
ID model DashScope mana yang saya gunakan untuk Qwen3.5-Omni?
Gunakan qwen3.5-omni-plus, qwen3.5-omni-flash, atau qwen3.5-omni-light tergantung pada kebutuhan kualitas dan latensi Anda. Mulailah dengan Flash untuk sebagian besar kasus penggunaan.
Bisakah saya menggunakan OpenAI Python SDK dengan DashScope?
Ya. Atur base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" dan gunakan kunci DashScope Anda sebagai api_key. Format permintaan dan respons identik dengan OpenAI API.
Bagaimana cara mengirim beberapa file (audio + gambar) dalam satu permintaan?
Tempatkan mereka dalam array content sebagai objek bertipe terpisah di samping prompt teks Anda. Keempat modalitas dapat muncul dalam pesan yang sama.
Apakah ada batasan ukuran untuk file audio atau video?
DashScope memiliki batasan payload per permintaan. Untuk file besar, gunakan referensi URL alih-alih pengkodean base64. Host file di penyimpanan yang dapat diakses dan berikan URL di bidang audio atau video_url.
Bagaimana cara menonaktifkan keluaran audio dan hanya mendapatkan teks?
Atur modalities=["text"] atau hilangkan parameter modalities. Respons hanya teks lebih cepat dan lebih murah.
Apakah ini mendukung pemanggilan fungsi/alat?
Ya. Gunakan parameter tools standar dengan definisi fungsi, sama seperti model yang kompatibel dengan OpenAI lainnya. Model mengembalikan objek panggilan alat terstruktur yang Anda jalankan dalam kode Anda sendiri.
Apa cara terbaik untuk menangani rekaman audio yang panjang?
Untuk rekaman di bawah 10 jam, kirim sebagai satu permintaan. Untuk rekaman yang lebih panjang, pisahkan pada titik jeda alami dan proses setiap segmen secara terpisah. Gabungkan hasilnya di lapisan aplikasi Anda.
Bagaimana cara menguji permintaan multimodal saya sebelum membangun aplikasi penuh?
Gunakan Apidog untuk membangun dan menyimpan template permintaan untuk setiap modalitas. Anda dapat beralih antara varian model, memeriksa struktur respons lengkap, dan menulis pernyataan yang memverifikasi kualitas keluaran tanpa menulis kode aplikasi terlebih dahulu.