Guia da API do Vidu AI para Image-to-Video e Reference Video

A API Vidu AI transforma uma imagem estática em um clipe de movimento com uma única requisição, e o modo de vídeo de referência transfere o movimento de um clipe existente para uma imagem estática. Este tutorial percorre o acesso a ambas as capacidades através da API unificada da TokenLab, incluindo a estrutura de payload, ajuste de parâmetros e um checklist de implementação prática.

Principais pontos

• O endpoint de image-to-video do Vidu gera movimento realista a partir de um quadro estático; o modo de vídeo de referência copia padrões de movimento precisos de um vídeo para o conteúdo de uma imagem alvo.
• A TokenLab expõe o Vidu e outros modelos de vídeo: como Seedance, Veo 3, Kling, Hailuo e PixVerse V6: através de uma única API consistente, para que você possa comparar qualidade, velocidade e custo sem alterar seu código de integração.
• Parâmetros como motion_intensity, num_frames e reference_video controlam diretamente o estilo de saída, a duração e a fidelidade; ajustá-los afeta a latência de geração e a qualidade do resultado.
• Os preços e a disponibilidade dos modelos mudam com frequência; verifique sempre os detalhes mais recentes no diretório de modelos da TokenLab e na página de comparação de preços (ambos observados em 07/07/2026).

Entendendo os modos Image-to-Video e Reference Video do Vidu

O pipeline de image-to-video do Vidu trata uma imagem de entrada estática como o primeiro quadro e preenche os quadros restantes usando um prior de movimento aprendido a partir de dados de vídeo. O modelo prevê o fluxo óptico e as mudanças de aparência consistentes com a semântica da cena, gerando um clipe de vídeo curto: geralmente de 2 a 10 segundos, dependendo de num_frames e da resolução escolhida.

O modo de vídeo de referência, às vezes chamado de transferência de movimento ou geração guiada por vídeo, aceita um parâmetro adicional reference_video. O modelo extrai vetores de movimento do clipe de referência e os aplica ao conteúdo da imagem estática. Por exemplo, os movimentos de um dançarino de um vídeo podem ser transferidos para uma foto de retrato, ou o movimento de câmera (pan) de uma vitrine de produto pode ser mapeado para uma imagem de produto diferente. Ambos os modos compartilham o mesmo endpoint de API na TokenLab; a única diferença é a presença de um campo reference_video na requisição.

Ao contrário dos modelos de text-to-video que alucinam movimento a partir de um prompt, a abordagem condicionada por imagem do Vidu oferece controle preciso sobre o quadro inicial e, com um vídeo de referência, a coreografia de movimento exata. Isso o torna adequado para animar arte conceitual estática, adicionar movimento secundário a fotos de produtos ou criar testes de animação de personagens a partir de uma única referência. Como o modelo trabalha com um primeiro quadro real, o clipe gerado permanece ancorado à identidade visual da entrada, evitando problemas de distorção de forma comuns em pipelines baseados apenas em prompts.

Configurando sua conta TokenLab e chave de API

Para usar o Vidu através da TokenLab, você precisa de uma conta ativa e uma chave de API.

1. Inscreva-se em tokenlab.sh.
2. Navegue até seu painel e gere uma chave de API em API Keys.
3. Armazene a chave com segurança: ela será enviada como um bearer token em cada requisição.

A API unificada da TokenLab permite que você alterne entre modelos de vídeo apenas alterando o campo model no payload. O Vidu é identificado pelo nome vidu. Seu código de integração existente para modelos como Seedance ou Veo 3 funcionará com o Vidu sem alterações estruturais.

Fazendo sua primeira requisição de API Vidu com a TokenLab

Uma requisição básica de image-to-video envia uma URL de imagem estática e um conjunto de parâmetros de geração. Aqui está um exemplo usando curl:

curl -X POST "https://api.tokenlab.sh/v1/video/generate" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vidu",
    "image_url": "https://example.com/portrait.jpg",
    "motion_intensity": 0.7,
    "num_frames": 120,
    "resolution": "1080p"
  }'

Para o modo de vídeo de referência, adicione um parâmetro reference_video apontando para um clipe de movimento curto:

{
  "model": "vidu",
  "image_url": "https://example.com/portrait.jpg",
  "reference_video": "https://example.com/dance_reference.mp4",
  "motion_intensity": 0.8,
  "num_frames": 120
}

A API retorna um objeto JSON com uma video_url que você pode consultar (poll) até que a geração esteja concluída. A TokenLab também suporta callbacks via webhook para evitar polling, que é a abordagem preferida para cargas de trabalho de produção.

Ajustando parâmetros para qualidade e velocidade

O endpoint do Vidu aceita vários parâmetros que afetam o realismo do movimento, a duração da saída e o tempo de processamento. A tabela abaixo resume os mais importantes.

Parâmetro	Tipo	Descrição	Intervalo Típico
motion_intensity	float	Controla a amplitude do movimento. Valores menores produzem movimento sutil; valores maiores criam ações mais dramáticas.	0.0 – 1.0
num_frames	int	Número de quadros a serem gerados. A duração da saída é num_frames / fps, onde o fps padrão é 24. Valores maiores aumentam o tempo de geração.	48 – 240
resolution	string	Resolução de saída. Valores suportados são 720p e 1080p. Resoluções maiores custam mais e levam mais tempo.	720p, 1080p
reference_video	string	URL de um vídeo de referência para transferência de movimento. Quando omitido, o modelo gera movimento autonomamente.	URL
style_strength	float	O quanto o modelo adere ao estilo visual da imagem de entrada versus o movimento de referência. Um valor de 1.0 mantém o estilo da imagem; valores menores permitem que o estilo do vídeo de referência se misture levemente.	0.0 – 1.0

Testar esses parâmetros em um clipe curto (48–60 quadros) antes de escalar para a duração total pode economizar tempo e custo. A página de preços da TokenLab mostra custos em tempo real por geração, que variam de acordo com a resolução e a contagem de quadros. O diretório de modelos também lista os provedores oficiais onde o Vidu está hospedado, como Replicate e fal, cujos preços são observados independentemente: verifique os preços da Replicate e os preços da fal para as taxas mais recentes (observadas em 07/07/2026).

Checklist de implementação prática

Antes de entrar em produção, use este checklist para confirmar se sua integração está pronta.

• Chave de API com escopo correto – A chave não tem permissões mais amplas do que o necessário para a geração de vídeo.
• Imagem de entrada validada – A URL da imagem é publicamente acessível e tem pelo menos 512×512 pixels; o modelo funciona melhor com rostos ou objetos claros e bem iluminados.
• Vídeo de referência preparado – Ao usar transferência de movimento, o clipe de referência é curto (2–5 segundos), bem cortado e contém um único movimento contínuo sem cortes de cena.
• Ajuste de parâmetros concluído – motion_intensity e num_frames foram testados em uma amostra; o equilíbrio escolhido atende ao seu orçamento de latência e limite de qualidade visual.
• Polling ou webhook configurado – O cliente consulta o status da video_url ou aguarda o webhook de conclusão para evitar bloquear a thread principal.
• Tratamento de erros implementado – O código tenta novamente de forma elegante em erros 5xx e registra quaisquer respostas 4xx para depuração.
• Monitoramento de custos ativado – Um limite de gastos é definido no seu painel da TokenLab, e você consulta a página de comparação de preços regularmente conforme os custos evoluem.
• Fallback de modelo considerado – Se o Vidu estiver temporariamente indisponível, mudar para Seedance ou Veo 3 requer apenas uma alteração no campo model na TokenLab.

Seguir esses passos ajuda a manter seu pipeline confiável mesmo à medida que a oferta de modelos de vídeo muda.

Comparando o Vidu com outros modelos de vídeo

A API unificada da TokenLab permite que você teste o Vidu contra vários outros geradores de vídeo sem reescrever o código de integração. As principais alternativas no momento da redação (07/07/2026) são Seedance, Veo 3, Kling, Hailuo e PixVerse V6: todos disponíveis sob o mesmo endpoint. Cada um tem pontos fortes distintos:

• Seedance – Excelente em animação de personagens fluida e com alta taxa de quadros; frequentemente preferido para cenas de dança e ação.
• Veo 3 – Produz movimentos de câmera cinematográficos e composição de cena; forte para vídeos de produtos e curtas-metragens.
• Kling – Otimizado para movimento humano realista e sincronia labial; útil para avatares de "talking-head".
• Hailuo – Foca em efeitos estilizados e animados; funciona bem para motion graphics.
• PixVerse V6 – Equilibra velocidade e qualidade para clipes de redes sociais em massa.

Uma análise detalhada desses modelos, incluindo amostras de saída lado a lado e recomendações de casos de uso, está disponível no artigo melhores APIs de modelos de vídeo IA 2026. Para desenvolvedores que precisam rotear entre provedores com base no custo, o guia de comparação do OpenRouter explica como a TokenLab abstrai o acesso a múltiplos provedores e ajuda a minimizar os gastos.

FAQ

1. O Vidu suporta prompts de texto junto com uma imagem?
   O Vidu é principalmente um modelo condicionado por imagem; a imagem atua como o primeiro quadro e o prior de movimento determina o movimento. Embora alguns provedores possam permitir uma dica de texto opcional para ajustar o estilo, a API através da TokenLab atualmente não aceita um campo prompt. A melhor maneira de influenciar a saída é ajustando motion_intensity, num_frames e, crucialmente, usando um vídeo de referência adequado.

2. Quanto tempo leva uma geração típica?
   A latência de geração depende de num_frames, resolução e carga do provedor. Um clipe de 2 segundos a 720p (48 quadros) geralmente é concluído em 15–30 segundos na TokenLab. Um clipe de 5 segundos a 1080p (120 quadros) pode levar de 60–90 segundos. A entrega via webhook é recomendada para aplicações sensíveis ao tempo.

3. Posso usar imagens ou vídeos hospedados localmente?
   A TokenLab requer URLs acessíveis publicamente para image_url e reference_video. Você pode fazer upload de arquivos para um bucket de armazenamento em nuvem (por exemplo, Amazon S3 com uma URL pré-assinada) ou usar um serviço de hospedagem temporária. Os provedores subjacentes do Vidu (Replicate, fal) também exigem URLs para a busca de ativos.

Comece com o Vidu na TokenLab

A API Vidu AI está pronta para seus projetos de image-to-video e transferência de movimento. Inscreva-se em uma conta TokenLab, obtenha sua chave de API e envie sua primeira requisição de teste hoje. Explore o diretório de modelos da TokenLab para selecionar o Vidu e compará-lo com outros geradores de vídeo, ou mergulhe na página de comparação de preços para otimizar seus custos. Com uma única API, você obtém acesso a toda a linha de modelos de vídeo: sem necessidade de trocas de integração.