Guia da API Vidu: modelo MoE e acesso à série Q

Se eu tivesse que resumir em uma linha: use o Vidu MoE para lógica de prompt mais difícil, use o Q3 Pro para a saída final e use o Q3 Turbo para testes de menor custo, tudo em uma única APIMart.

Aqui está a versão resumida que você pode aplicar já:

• Eu consigo acessar Vidu MoE, Vidu Q3 Pro e Vidu Q3 Turbo pela APIMart com uma chave de API e um fluxo principal de requisição.
• O endpoint central é POST https://api.apimart.ai/v1/videos/generations.
• Os jobs de vídeo são assíncronos, então recebo um task_id primeiro, depois faço polling de GET /v1/tasks/{task_id} ou uso callback_url.
• O Vidu suporta:
  • texto-para-vídeo
  • imagem-para-vídeo
  • vídeo baseado em referência
  • transições de primeiro-último quadro
• Os modelos Q3 adicionam áudio integrado como diálogo, efeitos sonoros e música.
• Os clipes podem durar até 16 segundos, com saída em 540p, 720p ou 1080p.
• O preço da APIMart no artigo lista:
  • Q3 Pro: cerca de $0.12/seg em 720p
  • Q3 Turbo: cerca de $0.048/seg em 720p
• Os links de saída expiram após 24 horas, então devo baixar os arquivos logo após o sucesso.

Comparação rápida

O que se destaca para mim é o quão simples é a troca: na maioria dos casos, eu só mudo o campo model e mantenho o resto da configuração igual. Isso faz o artigo ser menos sobre trabalho de configuração e mais sobre escolher o modelo certo para custo, tempo de espera e qualidade de saída.

Modelos Vidu explicados: MoE vs. série Q

O modelo MoE do Vidu: o que é e quando usá-lo

O modelo MoE (Mixture of Experts) envia diferentes partes de uma tarefa de geração para especialistas dedicados a movimento, consistência de cena e controle de prompt. Ele faz mais sentido para prompts multi-cena ou mais longos, onde a consistência importa mais do que a velocidade pura.

Há uma ressalva, porém. O MoE exige mais computação e tem entrega mais lenta que a série Q ^[7]. Para prompts simples, ele costuma ser mais do que você precisa.

Série Q do Vidu e Vidu Q3 Pro: desempenho para uso em produção

Se o MoE é o especialista, a série Q é a opção feita para trabalho de produção. O Vidu Q3 Pro foi projetado para saída cinematográfica refinada e vídeos guiados por storyboard ^[7]. Ele suporta vídeo em 1080p, clipes de até 16 segundos e geração de áudio-vídeo com diálogo e efeitos sonoros sincronizados ^[1][2][4]. Na APIMart, o Q3 Pro começa em $0.12 por segundo ^[2][3].

O Vidu Q3 Turbo pende mais para velocidade e menor custo, com troca de cena mais rápida ^[6][7]. Na APIMart, o Q3 Turbo começa em $0.048 por segundo ^[3].

Como escolher entre MoE e série Q para o seu fluxo

Essa escolha se resume principalmente à complexidade do prompt, ao tempo de entrega e ao orçamento. Se o seu fluxo depende de seguimento estrito de instruções e lógica multi-cena, vá com o MoE. Se você precisa de saída refinada com sincronia áudio-visual, o Q3 Pro é o melhor encaixe. Como alternativa, o Kling V3 oferece outra opção de alta fidelidade para vídeo de IA cinematográfico. Se o seu objetivo principal é iteração rápida ou menor custo por clipe, o Q3 Turbo é a escolha prática.

A tabela abaixo mapeia cada modelo ao tipo de trabalho que ele lida melhor. Para quem compara opções de alto nível, o Sora 2 oferece capacidades cinematográficas semelhantes com áudio sincronizado.

A seguir, veja como selecionar um modelo, autenticar e enviar a requisição pela APIMart.

Como acessar o Vidu pela APIMart

Configuração de conta, autenticação e tratamento de chave de API

Depois de escolher um modelo, você pode enviar jobs pela APIMart com uma chave de API. Primeiro, crie uma conta na APIMart e gere sua chave na página de gerenciamento de chaves de API no dashboard ^[2][3].

Envie cada requisição com um token Bearer no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Para armazenamento, mantenha as chaves em variáveis de ambiente ou em um gerenciador de segredos como o AWS Secrets Manager ou o GCP Secret Manager. Também ajuda usar chaves separadas para desenvolvimento, staging e produção. Se uma chave for exposta, rotacione-a imediatamente. Faça o mesmo em uma agenda fixa. E, ao registrar requisições, salve apenas o task_id - nunca o token em si ^[5].

Encontrando modelos Vidu, preços e esquema de entrada na APIMart

Uma vez logado, confira o catálogo antes de enviar qualquer coisa. É lá que você pode confirmar nomes de modelos, entradas suportadas e preços atuais. No catálogo da APIMart, os modelos Vidu estão listados em Geração de vídeo. Você também pode encontrar outros modelos de alto desempenho como o MiniMax-Hailuo-02 na mesma categoria. Use essa página para comparar esquema de entrada, resolução e custo por segundo entre MoE, Q3 Pro e Q3 Turbo ^[2][3].

Os principais campos a observar são:

• model
• prompt
• duration
• resolution
• aspect_ratio

Para jobs de texto-para-vídeo, use aspect_ratio. Para jobs baseados em imagem, o sistema usa a proporção da imagem de origem ^[2]. Os prompts de texto são limitados a 2.000 caracteres ^[2][3].

Endpoints, estrutura de requisição e tratamento de jobs assíncronos

Depois de escolher o modelo, envie a requisição de geração e acompanhe o job assíncrono com o task_id retornado. Envie uma requisição POST para https://api.apimart.ai/v1/videos/generations, depois faça polling do status do job com GET https://api.apimart.ai/v1/tasks/{task_id} ^[2][5].

Os jobs passam por estes estados:

• submitted
• queueing
• processing
• success ou failed

Se você quer que a APIMart notifique seu app quando o job estiver pronto, adicione callback_url e receba o resultado por webhook ^[5]. Assim que o job chega a success, baixe o arquivo imediatamente. A partir daí, você pode mapear os campos de requisição para um fluxo de texto-para-vídeo ou um fluxo baseado em referência.

Integração passo a passo para texto-para-vídeo e vídeo baseado em referência

Fluxo básico de texto-para-vídeo com seleção de modelo

Depois de escolher um modelo no catálogo, o fluxo de texto-para-vídeo é bem simples. Envie sua chave de API do lado do servidor no cabeçalho Authorization como Bearer {your_api_key}.

Aqui está um payload mínimo para um job de texto-para-vídeo com viduq3-pro:

{
  "model": "viduq3-pro",
  "prompt": "A red fox running through a snowy forest at dusk, cinematic slow motion",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true
}

A resposta inclui um task_id e um status como submitted, queueing ou processing. Depois disso, você pode fazer polling de GET /v1/tasks/{task_id} com o task_id retornado, ou passar um callback_url na requisição para que a plataforma notifique seu app quando o job chegar a success ou failed ^[1][7][10]. Se quiser mudar para viduq3-turbo, você praticamente só muda o campo model.

O padrão assíncrono permanece o mesmo entre os modos. O que muda são os campos de entrada.

Adicionando entradas de imagem ou referência e controles avançados

Para imagem-para-vídeo, passe uma URL de imagem no array image_urls. Use 0 imagens para texto-para-vídeo, 1 para imagem-para-vídeo e 2 para o modo primeiro-último quadro ^[2]. Nos modos baseados em imagem, a proporção da saída vem da imagem de origem, então você pode omitir aspect_ratio ^[2]. Se você envia arquivos diretamente em vez de usar URLs, mantenha cada imagem em formato PNG, JPEG ou WebP, abaixo de 50 MB, e mantenha o corpo HTTP total abaixo de 20 MB ^[9][8].

Para geração baseada em referência, use o endpoint /reference2video com um array subjects. Defina cada sujeito com um name e suas images, depois chame-o no prompt com @subjectname. Os modelos Q3 permitem até 7 imagens de referência ou descrições de texto no recurso subjects ^[6]. Se você usa o modo primeiro-último quadro, mantenha ambas as imagens próximas em proporção, idealmente dentro de uma razão de 0,8 a 1,25, para reduzir falhas ^[8]. Quando rostos ou mãos estão envolvidos, mantenha os prompts de movimento sutis para reduzir artefatos de distorção ^[5].

A tabela abaixo mostra os principais parâmetros nos dois fluxos:

Defina um seed fixo durante os testes se quiser o mesmo resultado visual entre execuções ^[2][9]. Para jobs em lote que não são urgentes, defina off_peak como true. Essas tarefas costumam ser concluídas dentro de 48 horas e usam menos créditos ^[1][6].

Rastreando uso, custo e confiabilidade em produção

Uma vez que sua requisição esteja funcionando, o próximo trabalho é manter custo e confiabilidade sob controle em produção.

Registre o task_id e o timestamp de cada requisição. Isso lhe dá uma forma segura de depurar sem armazenar credenciais sensíveis ^[5]. Também ajuda rastrear o tempo de fila e o tempo de geração separadamente, para que você possa distinguir entre atraso de plataforma e latência de modelo.

Para estimativa de custo, o Vidu Q3 Pro em 720p custa cerca de $0.12 por segundo na APIMart, e o Q3 Turbo custa cerca de $0.048 por segundo ^[3]. Defina alertas automáticos em 50%, 80% e 100% do seu teto de orçamento mensal para que o gasto não fuja do controle ^[5].

As tentativas também importam. Em erros 5xx, use backoff exponencial: tente novamente em 2 segundos, depois 5 segundos, depois 15 segundos antes de mostrar um erro ao usuário ^[5]. Os modelos da série Vidu Q3 vêm com um SLA de 99,9% para cargas de produção ^[3], mas falhas de curta duração ainda acontecem, então as tentativas devem fazer parte de qualquer build de produção.

Checklist de seleção de modelo e principais conclusões

Checklist de caso de uso para devs, criadores e equipes de produto

Escolha com base em três coisas: complexidade do prompt, velocidade e qualidade de saída. A tabela abaixo transforma a comparação de modelos em uma escolha prática de entrega.

Depois de escolher uma linha, mantenha o mesmo esquema de requisição da seção de integração. Em palavras simples: comece as ideias no Q3 Turbo, depois leve a renderização final em 1080p para o Q3 Pro. É um fluxo simples e ajuda você a se mover rápido sem gastar mais do que precisa.

Para clipes onde a fidelidade de movimento importa mais, mire em 5 a 10 segundos em vez de esticar até o máximo de 16 segundos. Clipes mais curtos costumam dar movimento mais apertado e menos dor de cabeça.

Pontos-chave para lembrar antes de entregar

O MoE é a escolha para lógica complexa multi-cena. O Q3 Pro lhe dá saída cinematográfica de alta fidelidade em 1080p ^[3]. O Q3 Turbo é a opção de menor custo a $0.048/seg em 720p ^[3].

Na APIMart, alternar entre esses modelos é apenas uma única mudança do parâmetro model. Todo o resto da requisição permanece igual ^[3]. Isso significa que você pode testar um modelo, trocar para outro e manter seu trabalho de integração estável.

Use o mesmo fluxo assíncrono sempre:

• Envie a requisição
• Capture o task_id
• Faça polling do status ou use callback_url

Além disso, baixe os vídeos gerados logo após estarem prontos. Os links de saída expiram após 24 horas ^[3][11].

Perguntas frequentes

Com qual modelo Vidu devo começar?

Comece com o modelo que se encaixa nas suas necessidades de velocidade, áudio e controle visual.

• viduq3-pro: melhor para sincronia áudio-visual e segmentação de planos
• viduq3-turbo: geração mais rápida que a versão pro
• viduq1 ou viduq2: escolhas sólidas para produção estável de vídeo e movimento de câmera confiável

Como rastreio um job de vídeo após enviá-lo?

Você pode rastrear sua tarefa de geração de vídeo de duas formas.

Para uso em produção, a melhor opção é incluir um callback_url na sua requisição inicial. Quando você faz isso, a API Vidu envia atualizações da tarefa e metadados de resultado direto para sua URL automaticamente. Isso significa que você não precisa ficar checando o status da tarefa por conta própria.

A outra opção é fazer polling da API de consulta de status com o task_id que você recebe após o envio. Quando o estado da tarefa muda para success, a resposta incluirá a URL de download do vídeo e outros metadados relacionados.

Que entradas e limites devo conhecer antes de integrar?

Antes de integrar a API Vidu, garanta que suas entradas fiquem dentro destes limites:

• Imagens: apenas PNG, JPEG, JPG ou WebP; cada arquivo deve ter menos de 50 MB e pelo menos 128×128 pixels
• Corpo HTTP total da requisição: máximo de 20 MB
• Prompts de texto: até 5.000 caracteres
• Dados de passthrough do payload: até 1.048.576 caracteres

Os limites de duração dependem do modelo que você usa. O Q3 suporta 1 a 16 segundos, o Q2 suporta 1 a 10 segundos e o Q1 suporta 5 segundos.

Além disso, mantenha suas chaves de API seguras. Não as exponha em código do lado do cliente. Envie as requisições por um intermediário do lado do servidor.