Guia da API Vidu MoE: vídeo Mixture-of-Experts

Se eu tivesse que resumir isto em uma linha: Vidu MoE é uma API de vídeo de formato curto para equipes que precisam de clipes de 1–16 segundos, até 1080p, 24 fps, entrega assíncrona e áudio opcional em uma única requisição.

Se você está avaliando o encaixe para produção, aqui vai a resposta curta: ela funciona melhor quando você consegue lidar com jobs assíncronos, orçar para refações e escolher o nível de modelo certo para cada etapa. Eu usaria viduq3-turbo para previews e viduq3-pro para a saída final. A maioria dos jobs termina em cerca de 60–120 segundos em 720p e 90–180 segundos em 1080p, com tempos de espera de pico chegando a cerca de 4 minutos.

Aqui está o que mais importa:

• Modos de entrada: texto-para-vídeo, animação de uma imagem, alternativas ao Grok Imagine Video, vídeo de dois quadros (início/fim) e entrada de referência de múltiplas imagens
• Limites de clipe: 1 a 16 segundos
• Saída: até 1080p a 24 fps
• Áudio: pode ser ligado na mesma requisição
• Referências de imagem: até 7 imagens no conjunto de recursos mais amplo do modelo
• Regra principal da API: se você enviar URLs de imagem, não envie aspect_ratio
• Entrega: assíncrona com task_id, polling ou callback
• Exemplo de preço: o Pro fica em cerca de $0,60 para 5 segundos e $1,44 para 12 segundos
• Realidade do orçamento: planeje 2–3 tentativas por clipe aprovado

Alguns detalhes se destacam. A API usa uma requisição JSON simples com model, prompt e entradas de mídia opcionais. A escolha do modelo é direta: turbo para testes de menor custo, pro para renderizações de ponta. O controle de seed ajuda a manter as saídas numa direção semelhante entre as refações, embora não como correspondências exatas.

Se eu estivesse avaliando isto para uma equipe de produto, focaria em três perguntas:

1. Meu app consegue lidar com processamento assíncrono de forma limpa?
2. Eu preciso de geração apenas por prompt, controle conduzido por imagem ou controle por quadro inicial/final?
3. Meu orçamento ainda funciona depois das refações, não só com o custo da primeira passagem?

Comparação rápida

Então, antes de ler o guia completo, a conclusão é simples: o Vidu MoE é um bom encaixe para geração de vídeo curta baseada em API quando você quer vários modos de entrada, áudio embutido e controle de custo alternando entre turbo e pro. O resto depende da configuração da requisição, do tratamento de status e da escolha do método de entrada que combina com seu fluxo.

Visão geral da API Vidu MoE e capacidades principais

No nível da API, o Vidu MoE mapeia para um pequeno conjunto de nomes de modelo, fluxos e campos de saída.

O Vidu MoE aparece na API como viduq3-mix, o modelo Q3 balanceado. O viduq3-turbo tende à velocidade, enquanto o viduq3-pro tende a mais detalhe.

O que Mixture-of-Experts significa na geração de vídeo

O mixture-of-experts envia diferentes partes do processo de geração para componentes especializados. Na prática, isso ajuda com movimento, composição de cena e aderência ao prompt.

A série Q3 também suporta troca inteligente de cena e troca inteligente de câmera ^[2][4]. Isso importa mais em sequências de múltiplas tomadas, onde a continuidade pode desmoronar rápido se o modelo perde o controle da cena.

Fluxos suportados: texto-para-vídeo, imagem-para-vídeo e geração guiada por referência

A partir daí, a principal diferença depende do tipo de entrada que você envia.

O viduq3-mix suporta quatro fluxos:

• Texto-para-Vídeo a partir de um prompt apenas
• Imagem-para-Vídeo a partir de uma imagem inicial
• Referência-para-Vídeo a partir de 1 a 7 imagens para consistência de aparência e estilo
• Início-Fim para Vídeo a partir de dois quadros que definem a transição

Os prompts suportam até 5.000 caracteres ^[3][4]. O viduq3-mix não suporta a biblioteca de entidades Subjects.

Entradas e saídas num relance

Cada job retorna um task_id e state, e o video_url final fica disponível após o processamento.

Os vídeos Q3 rodam a 24 fps, suportam durações de 1 a 16 segundos (comparável às capacidades do Sora 2) e oferecem saída em 540p, 720p ou 1080p ^[2]. As entradas de imagem são limitadas a 50 MB por arquivo ^[4][1].

Essas opções de fluxo moldam o payload que você envia em seguida, que a próxima seção detalha em autenticação e formato de requisição.

Autenticação, estrutura de requisição e configuração na APIMart

Para gerar vídeos Vidu MoE, você precisa enviar uma requisição JSON autenticada. O corpo da requisição depende do modo de entrada: apenas texto, imagem única ou múltiplas imagens.

Obtendo credenciais de API e definindo cabeçalhos de requisição

Gere sua chave de API na Página de Gerenciamento de Chaves de API da APIMart ^[6]. Salve-a como APIMART_API_KEY, depois carregue-a em tempo de execução com os.environ.get("APIMART_API_KEY") em Python ou process.env.APIMART_API_KEY em Node.js.

Inclua estes cabeçalhos em toda requisição:

• Authorization: Bearer YOUR_API_KEY
• Content-Type: application/json

Payload mínimo de requisição para um job de geração de vídeo

O endpoint padrão da APIMart para gerações Vidu Q3 (MoE) é https://api.apimart.ai/v1/videos/generations ^[6]. A API descobre o modo a partir de image_urls:

• 0 URLs = texto-para-vídeo
• 1 URL = imagem-para-vídeo
• 2 URLs = primeiro-para-último quadro

Aqui estão os campos principais e quando usá-los ^[6]:

Um erro fácil aqui: não envie aspect_ratio com image_urls. Quando você inclui imagens, a API extrai a proporção da imagem de origem. Se você enviar aspect_ratio mesmo assim, a requisição retorna um erro 400.

Uma vez definido o payload, você pode enviar o job e começar a fazer polling do resultado.

Exemplo de chamada de API e padrão de resposta

Exemplo de requisição texto-para-vídeo:

curl -X POST https://api.apimart.ai/v1/videos/generations \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "A product shot of a glass perfume bottle on a marble surface, camera slowly zooms in, soft studio lighting",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false
  }'

Um envio bem-sucedido retorna um task_id e status submitted ^[6]:

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_xxxxxxxxxx"
  }]
}

A API roda de forma assíncrona. Isso significa que a primeira resposta só te diz que o job foi aceito. Use o task_id para fazer polling no endpoint "Get Task Status". Quando o job termina, a resposta inclui o(s) link(s) MP4, geralmente válido(s) por 7 dias ^[6].

Um ritmo de polling simples funciona bem:

• Faça polling a cada 5 segundos nos primeiros 5 minutos
• Depois disso, faça polling uma vez por minuto
• Continue fazendo polling até o status ser completed

Nesse ponto, baixe e armazene o(s) link(s) de vídeo retornado(s).

A seguir, ajuste duração, resolução, proporção e entradas de referência para controlar o vídeo final. Para projetos que exigem estilos cinematográficos diferentes, você também pode comparar as capacidades do Kling V3 para geração de vídeo de ponta.

Fluxo de geração, parâmetros e controle de saída

Fluxo de ponta a ponta: enviar, monitorar, recuperar e armazenar resultados

Depois de enviar um job, a grande decisão de produção é simples: usar um callback ou fazer polling do status. Na maioria dos casos, callback_url é a melhor escolha para produção. O polling funciona, mas deve ser seu plano reserva. Quando você usa um callback, a API envia o status final para o seu endpoint. Se a entrega falhar, ela tenta novamente até três vezes ^[3].

O job então passa por um caminho de status fixo: created → queueing → processing → success ou failed ^[3][4]. Se uma tarefa cai em failed, a resposta inclui um código de erro. Registre esse código e trate-o no seu fluxo para que sua equipe possa identificar padrões e corrigir problemas mais rápido.

Quando o status chega a success, baixe a saída imediatamente e salve-a em armazenamento durável. Esse passo importa porque as URLs hospedadas pela API podem expirar ^[9].

Parâmetros-chave que afetam composição, movimento, duração e consistência

Uma vez que um job está em movimento, alguns parâmetros moldam como o resultado fica, quão estável ele se mantém de rodada para rodada e quantos créditos você gasta.

Um parâmetro vale a pena rastrear desde o início: seed. Se você obtém um padrão de movimento de que gosta, registre esse inteiro e guarde-o. Então, quando ajustar o prompt depois, você pode reutilizar o mesmo seed para segurar uma composição geral semelhante em vez de começar do zero.

Quando usar apenas prompts, referências de imagem ou ambos

Esses modos de entrada te deixam trocar velocidade por controle. Escolha o que combina com quão definida está sua direção visual.

• Apenas prompt (texto-para-vídeo): Melhor para ideação inicial, testes de estilo e experimentos de cena antes de os ativos visuais estarem finalizados. Use viduq3-turbo em 540p ou 720p para manter os custos de iteração mais baixos, ou compare com a WAN 2.6 para alternativas de alta consistência ^[7].
• Imagem única (imagem-para-vídeo): Melhor quando você quer animar algo específico, como uma foto de produto, ilustração de personagem ou visual de marca. É um encaixe forte para trabalho de e-commerce e marketing.
• Duas imagens (primeiro-para-último quadro): Melhor quando a transição precisa terminar em um resultado definido, como um produto girando para um certo ângulo ou um personagem se movendo para uma pose definida ^[5].

Se o prompt manual te dá resultados irregulares, ligue is_rec: true. A API gerará um prompt otimizado a partir da sua imagem, o que pode ajudar no alinhamento prompt-imagem, mas adiciona 10 créditos por tarefa ^[1].

Desempenho, preços e cenários reais de integração

Como avaliar latência, confiabilidade e custo por vídeo

Depois de fixar o formato da requisição, a próxima coisa a olhar é velocidade, preço e taxa de sucesso do job. Este é um fluxo assíncrono, então seu app deve enviar o job, armazenar o task_id e buscar o MP4 final depois por polling ou callback ^[3][6].

Os jobs geralmente passam por um caminho simples: na fila, completo ou falhou. Quando um job falha, os créditos costumam ser reembolsados automaticamente ^[3][10]. Isso importa em produção, porque refações fazem parte do processo, não são um caso isolado.

Em termos de tempo de resposta, as gerações em 720p geralmente terminam em 60–120 segundos. Para 1080p, espere algo mais como 90–180 segundos. O tempo de fila costuma ser 15–30 segundos em horários fora de pico, enquanto a latência p95 de pico pode se estender a cerca de 4 minutos ^[7]. Então sim, ela pode funcionar bem em produção - mas só se seu sistema for construído para lidar com a conclusão assíncrona de forma limpa.

Em preços, a taxa Pro coloca um clipe de 5 segundos em $0,60 e um clipe de 12 segundos em $1,44 ^[10]. Na prática, a maioria das equipes deve orçar para 2–3 tentativas por ativo aprovado. Isso coloca o custo final de um clipe utilizável na faixa de $1,20–$4,32, dependendo da duração ^[10]. Se você está em modo de teste, o viduq3-turbo é cerca de metade do preço do Pro e faz mais sentido para iteração rápida. O Pro é melhor guardado para renderizações finais ^[10].

Esses números cobrem apenas a geração base. Eles não incluem refações. Se sua equipe espera múltiplas passagens - e a maioria espera - multiplique os totais por 2–3 para um orçamento mais próximo da produção do dia a dia.

Casos de uso: vídeos de marketing, clipes educacionais e visuais de produto para e-commerce

Uma vez que custo e tempo de espera estão claros, o próximo passo é escolher o modo de entrada certo para o ativo que você precisa entregar. A melhor escolha depende, na maior parte, de uma coisa: quanto controle visual você já tem.

Uma forma simples de pensar nisso:

• Se a consistência de marca importa, use Referência-para-Vídeo
• Se a imagem de origem já parece boa, use Imagem-para-Vídeo
• Se você precisa de movimento entre dois estados, use Primeiro-Último Quadro
• Se você quer muitas variantes de anúncio rápido, use Texto-para-Vídeo ou considere o MiniMax Hailuo 2.3 para saídas profissionais de alta consistência.

Para equipes tentando reduzir o tempo de edição, o áudio nativo é o que mais muda o fluxo. O áudio nativo corta o trabalho separado de busca e edição ^[8], o que pode remover passos extras de pós-produção para equipes que querem um clipe finalizado a partir de uma única passagem de geração. É aí que o modelo se torna mais útil: quando o objetivo é chegar perto de um ativo pronto para entrega sem fazer o arquivo passar por uma longa cadeia de transferências.

Conclusão: como decidir se o Vidu MoE se encaixa no seu fluxo de produção

O Vidu MoE faz sentido quando você precisa de clipes curtos de até 12–16 segundos, vários modos de entrada e áudio nativo em uma configuração de API assíncrona. O parâmetro seed pode ajudar a manter jobs repetidos seguindo aproximadamente a mesma direção, mas você não deve esperar que entradas idênticas produzam saídas bit a bit correspondentes ^[6][10]. Jobs que falham também tendem a disparar reembolsos automáticos de créditos ^[3][10].

Isso se encaixa em equipes que produzem vídeo de formato curto em escala, podem esperar alguns minutos pelos resultados e têm espaço no orçamento para refações. Se isso soa como seu fluxo, a APIMart te dá uma forma limpa de rodar criativos de marketing, visuais de produto e conteúdo explicativo por uma única superfície de API.

Perguntas frequentes

Qual modelo Vidu MoE eu devo usar primeiro?

Para a maioria dos desenvolvedores, o viduq3-turbo é o melhor lugar para começar. Ele te dá as velocidades de geração mais rápidas, uma forte relação preço-desempenho e recursos avançados como sincronização áudio-visual e troca inteligente de cena.

Vá com o viduq3-pro se você quer o conjunto de recursos mais completo. Ele inclui geração de storyboard e o alinhamento áudio-visual de mais alta qualidade. Ambos os modelos suportam vídeos de 1 a 16 segundos e resoluções de até 1080p.

Como eu devo lidar com jobs de vídeo que falham ou atrasam?

Use o ID da tarefa no seu fluxo assíncrono.

Para jobs que demoram mais, ou faça polling da API de status de tempos em tempos ou defina uma URL de callback para ser notificado quando a tarefa atingir um estado terminal.

Se um job falha, verifique o callback ou a resposta de status em busca de detalhes do erro.

Para estabilidade em produção, use backoff exponencial ao fazer polling para não esbarrar em limites de taxa.

Tarefas fora de pico que rodam por mais de 48 horas são canceladas automaticamente, e os pontos são reembolsados.

Qual modo de entrada oferece o maior controle?

A Geração de Múltiplos Quadros (Multi-Frame) te dá o maior controle sobre como um vídeo se move de um momento para o seguinte. Em vez de depender de um prompt ou de uma configuração de dois quadros, você pode mapear uma sequência de até 9 quadros-chave.

Esse controle extra importa. Para cada transição, você pode adicionar uma imagem específica e um prompt personalizado, de modo que a história visual siga o caminho que você quer, quadro a quadro.

Para usá-lo, envie suas imagens e prompts para o endpoint multiframe no array image_settings.