TL;DR
Qwen3.5-Omni aceita texto, imagens, áudio e vídeo como entrada e retorna texto ou fala em tempo real. Acesse-o através da API DashScope da Alibaba Cloud ou execute-o localmente via HuggingFace Transformers. Este guia abrange a configuração da API, exemplos de código funcionais para cada modalidade, clonagem de voz e como testar suas solicitações com o Apidog.
Com o que você está trabalhando
Qwen3.5-Omni é um único modelo que lida com quatro tipos de entrada simultaneamente: texto, imagens, áudio e vídeo. Ele retorna texto ou fala natural, dependendo de como você configura a solicitação.
Lançado em 30 de março de 2026, ele é construído sobre uma arquitetura Thinker-Talker com um backbone MoE. O Thinker processa a entrada multimodal e raciocina sobre ela. O Talker converte a saída em fala usando um sistema multi-codebook que começa a transmitir áudio antes que a resposta completa seja concluída.
Três variantes estão disponíveis:
- Plus: Qualidade mais alta, melhor para raciocínio e clonagem de voz
- Flash: Velocidade e qualidade equilibradas, recomendado para a maioria dos usos em produção
- Light: Menor latência, para cenários móveis e de borda
Este guia usa Flash para a maioria dos exemplos, pois é o ponto de partida certo para a maioria das aplicações. Troque para Plus onde você precisar de máxima qualidade.
Acesso à API via DashScope
A API DashScope da Alibaba Cloud é a principal maneira de usar o Qwen3.5-Omni em produção. Você precisará de uma conta DashScope e uma chave de API.
Passo 1: Crie uma conta DashScope
Vá para dashscope.aliyuncs.com e inscreva-se. Se você já tem uma conta Alibaba Cloud, use-a.
Passo 2: Obtenha sua chave de API
- Faça login no console DashScope
- Clique em API Key Management na barra lateral esquerda
- Clique em Create API Key
- Copie a chave (formato:
sk-...)
Passo 3: Instale o SDK
pip install dashscope
Ou use o endpoint compatível com OpenAI diretamente com o SDK openai:
pip install openai
DashScope expõe uma API compatível com OpenAI em https://dashscope.aliyuncs.com/compatible-mode/v1, o que significa que você pode trocar seu base_url e usar o mesmo código que escreveria para OpenAI.
Entrada e saída de texto
Comece com o caso mais simples: texto de entrada, texto de saída.
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)
Mude para qwen3.5-omni-plus para tarefas de raciocínio mais difíceis ou qwen3.5-omni-light quando a latência for a prioridade.
Entrada de áudio: transcrição e compreensão
Passe um URL de arquivo de áudio ou áudio codificado em base64. O modelo transcreve, compreende e raciocina sobre o conteúdo nativamente. Nenhuma etapa ASR separada é necessária.
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)
O modelo lida com 113 idiomas para reconhecimento de fala. Você não precisa especificar o idioma; ele o detecta automaticamente.
Formatos de áudio suportados: WAV, MP3, M4A, OGG, FLAC.
Saída de áudio: conversão de texto em fala na resposta
Para obter fala em vez de texto, defina o parâmetro modalities e configure a saída de áudio:
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")
Duas vozes integradas estão disponíveis: Chelsie (feminina) e Ethan (masculina). A geração de fala funciona em 36 idiomas.
Entrada de imagem: compreensão visual
Passe um URL de imagem ou imagem codificada em base64 junto com uma pergunta de texto:
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)
Para imagens locais, codifique-as como 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?"
}
]
}
],
)
Entrada de vídeo: compreensão de gravações e capturas de tela
A entrada de vídeo é onde Qwen3.5-Omni faz algo que nenhum modelo de texto ou imagem pode fazer: raciocinar sobre as faixas visual e de áudio simultaneamente.
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)
Codificação de Vibração Audiovisual
O caso de uso "Vibe Coding" é passar uma gravação de tela e pedir ao modelo para gerar código a partir do que ele vê:
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)
A janela de contexto de 256K tokens comporta aproximadamente 400 segundos de vídeo 720p com áudio. Para gravações mais longas, corte ou divida.
Clonagem de voz
A clonagem de voz permite que você dê ao modelo uma voz alvo e faça com que ele responda nessa voz. Isso está disponível nas variantes Plus e Flash via 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))
Dicas para qualidade de clonagem de voz:
- Use uma gravação limpa, sem ruído de fundo
- 15-30 segundos funciona melhor do que clipes muito curtos
- Formato WAV em 16kHz ou superior
- A amostra de voz deve ter fala natural, não texto lido, para melhor correspondência de prosódia
Respostas em streaming
Para bate-papo por voz em tempo real ou aplicativos interativos, use streaming. O modelo começa a retornar áudio antes que a resposta completa seja gerada:
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)
O formato PCM16 funciona bem para streaming, pois você pode encaminhá-lo diretamente para um buffer de saída de áudio sem esperar por um arquivo completo.
Conversa multi-turno com modalidades mistas
Conversas reais misturam entradas em vários turnos. Veja como gerenciar o histórico de conversas com diferentes modalidades:
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?"}]))
A janela de contexto de 256K tokens significa que você pode manter longas conversas, incluindo aquelas com imagens e áudio incorporados, sem problemas de truncamento.
Implantação local com HuggingFace
Se você precisa executar Qwen3.5-Omni em sua própria infraestrutura:
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)
Requisitos de memória da GPU para implantação local:
| Variante | Precisão | VRAM Mínima |
|---|---|---|
| Plus (30B MoE) | BF16 | ~40GB |
| Flash | BF16 | ~20GB |
| Light | BF16 | ~10GB |
Para inferência local de produção, use vLLM em vez de HuggingFace Transformers. Modelos MoE rodam mais rápido com as otimizações de roteamento do vLLM.
Testando suas solicitações Qwen3.5-Omni com Apidog
Solicitações de API multimodais são mais difíceis de depurar do que JSON simples. Você está lidando com áudio e vídeo codificados em base64, arrays de conteúdo aninhados e respostas que podem incluir texto e áudio. Fazer isso a partir de um terminal se torna tedioso rapidamente.
Apidog lida com isso de forma limpa. Configure seu endpoint DashScope como uma nova coleção, armazene sua chave de API como uma variável de ambiente e construa modelos de solicitação para cada modalidade com a qual você está trabalhando.
Para cada variante (Plus, Flash, Light), você pode duplicar a solicitação base e alterar o parâmetro do modelo. Execute todas as três em sequência e compare as respostas, latência e qualidade da saída em uma única visualização.
Você também pode escrever asserções de teste no Apidog para verificar suas respostas multimodais:
- Verifique se
choices[0].message.contentnão está vazio para respostas de texto - Verifique se
choices[0].message.audio.dataestá presente quando a saída de áudio é solicitada - Afirme que a latência de resposta para Flash está abaixo do seu limite alvo
Isso é útil quando você está decidindo qual variante usar em produção.
Tratamento de erros e lógica de repetição
Limites de taxa e timeouts são comuns com grandes modelos multimodais, especialmente para entradas de vídeo. Construa o tratamento de repetição desde o início:
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")
Para entradas de vídeo maiores que 100MB, considere:
- Cortar para a parte relevante antes de enviar
- Reduzir a resolução para 480p se o conteúdo visual não exigir alta resolução
- Dividir gravações longas em segmentos e agregar os resultados
Problemas comuns e soluções
"A saída de áudio fica distorcida em números ou termos técnicos"Este é o problema que a tecnologia ARIA aborda. Certifique-se de que você está usando Qwen3.5-Omni (não uma versão anterior). Se você está auto-hospedando, use os pesos de modelo mais recentes do HuggingFace.
"O modelo continua falando quando envio uma interrupção de áudio"A interrupção semântica requer a variante Flash ou Plus. Light pode não ter esse recurso. Verifique também se você está transmitindo a resposta (não em lote) para que a interrupção funcione.
"A qualidade da clonagem de voz é ruim"A amostra de voz precisa estar limpa. Remova o ruído de fundo com uma ferramenta como o Audacity antes de fazer o upload. Use pelo menos 15 segundos de áudio. WAV a 16kHz ou 44.1kHz funciona melhor.
"A entrada de vídeo retorna um erro sobre limites de token"256K tokens cobrem aproximadamente 400 segundos de vídeo 720p. Vídeos mais longos precisam de corte ou resolução mais baixa. Verifique a duração do seu vídeo e reduza para menos de 6 minutos por segurança.
"A implantação local é muito lenta"Use vLLM, não HuggingFace Transformers, para inferência local de produção. Modelos MoE precisam das otimizações de roteamento do vLLM para uma taxa de transferência razoável.
FAQ
Qual ID de modelo DashScope devo usar para Qwen3.5-Omni?
Use qwen3.5-omni-plus, qwen3.5-omni-flash ou qwen3.5-omni-light dependendo das suas necessidades de qualidade e latência. Comece com Flash para a maioria dos casos de uso.
Posso usar o SDK Python do OpenAI com DashScope?
Sim. Defina base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" e use sua chave DashScope como api_key. O formato de solicitação e resposta é idêntico à API OpenAI.
Como faço para enviar vários arquivos (áudio + imagem) em uma única solicitação?
Coloque-os no array content como objetos tipados separados, junto com seu prompt de texto. Todas as quatro modalidades podem aparecer na mesma mensagem.
Existe um limite de tamanho para arquivos de áudio ou vídeo?
DashScope tem limites de payload por solicitação. Para arquivos grandes, use uma referência de URL em vez de codificação base64. Hospede o arquivo em um armazenamento acessível e passe o URL nos campos audio ou video_url.
Como desativo a saída de áudio e obtenho apenas texto?
Defina modalities=["text"] ou omita o parâmetro modalities. Respostas somente de texto são mais rápidas e mais baratas.
Ele suporta chamada de função/ferramenta?
Sim. Use o parâmetro tools padrão com definições de função, assim como com qualquer modelo compatível com OpenAI. O modelo retorna objetos de chamada de ferramenta estruturados que você executa em seu próprio código.
Qual é a melhor forma de lidar com gravações de áudio longas?
Para gravações com menos de 10 horas, envie-as como uma única solicitação. Para gravações mais longas, divida em pontos de pausa naturais e processe cada segmento separadamente. Agregue os resultados na sua camada de aplicação.
Como testo minhas solicitações multimodais antes de construir um aplicativo completo?
Use o Apidog para construir e salvar modelos de solicitação para cada modalidade. Você pode alternar entre variantes de modelo, inspecionar a estrutura completa da resposta e escrever asserções que verificam a qualidade da saída sem escrever código de aplicativo primeiro.