Tutorial da API de Imagens de Referência Veo: De Ativos a Vídeo

AI Overview

Quantas imagens de referência a API do Veo pode usar?

O Veo 3.1 aceita até três imagens de referência por pessoa, personagem ou produto. Use um conjunto pequeno e coerente que mostre claramente a identidade, os materiais e a forma, em vez de três composições não relacionadas.

Imagens de referência são iguais aos quadros inicial e final?

Não. referenceImages orienta a consistência do sujeito ou do estilo, enquanto image define o quadro inicial e lastFrame restringe o quadro final. Escolha um modo conforme o que deve permanecer fixo.

Qual modelo do Veo suporta imagens de referência?

A documentação atual do Gemini API do Google lista imagens de referência para o Veo 3.1 e o Veo 3.1 Fast, mas não para o Veo 3.1 Lite nem para o Veo 3.0. As gerações com imagens de referência usam uma duração de oito segundos.

O que uma integração da API deve salvar?

Salve os IDs dos ativos de entrada, o prompt normalizado, o modelo e a configuração, o nome da operação, o arquivo final e o resultado da revisão. Esse registro torna possível reproduzir uma geração falhada, em vez de transformar cada nova tentativa em mero palpite.

Escolha o Modo de Referência Antes de Codificar

A tarefa prática por trás de um tutorial da API de imagens de referência do Veo não é simplesmente enviar dados em base64. Os desenvolvedores precisam saber qual controle visual corresponde à cena, quais campos devem ser usados em conjunto e como recuperar-se quando a saída ignora um detalhe do produto ou se desvia do personagem.

Um novo conceito de conjunto de referência criado especificamente para este guia. O motociclista, a jaqueta cor açafrão, os óculos âmbar e a motocicleta azul-cobalto fornecem âncoras claras de continuidade; não é apresentado como um benchmark do Veo.

Comece selecionando um dos três modos:

Essa diferença é importante. Um retrato de personagem em referenceImages é uma orientação, não uma garantia de que o primeiro quadro renderizado reproduzirá esse retrato pixel a pixel. Por outro lado, uma image inicial trava a composição inicial, mas não fornece três vistas distintas da identidade. Não misture conceitos no prompt e depois culpe a API por escolher a restrição errada.

A tabela atual do Gemini API do Google indica que referenceImages suporta até três objetos VideoGenerationReferenceImage no Veo 3.1 e no Veo 3.1 Fast. O Veo 3.1 Lite não suporta esse campo. Uma solicitação com imagens de referência gera um único vídeo, usa uma duração de oito segundos, suporta orientações paisagem ou retrato e pode gerar em resoluções 720p, 1080p ou 4K nas rotas completas do Veo 3.1. Resoluções mais altas aumentam a latência e o custo, portanto valide o contrato da cena antes de escalar a entrega.

Para uma explicação mais ampla, no nível da interface, antes de construir o endpoint, consulte o Guia de fluxo do Google e do fluxo de trabalho do Veo.

Prepare as Imagens de Referência e o Prompt

Crie um conjunto coerente de ativos

Use referências que concordem quanto à identidade. Um pacote útil de três imagens pode conter uma visão limpa do rosto e da vestimenta, uma visão da geometria do produto e um pequeno acessório que deve ser mantido. Mantenha compatíveis a temperatura de cor, a distorção da lente e as proporções. Se uma imagem mostra uma motocicleta azul-cobalto e outra mostra um chassi diferente em azul-marinho, o prompt não poderá decidir de forma confiável qual geometria é a canônica.

Referência de personagem: examine a forma do rosto, o contorno do corte de cabelo curto, os painéis da jaqueta e as lentes âmbar. Uma referência legível é mais útil do que um retrato dramático, mas obscurecido.

Referência de produto: a geometria completa das rodas, o contorno do quadro, os painéis azul-cobalto, a jaqueta e os óculos são visíveis sob luz neutra pós-chuva.

Pré-processe as imagens antes da solicitação paga. Confirme o tipo MIME, rejeite arquivos vazios, decodifique uma vez para detectar corrupção e mantenha a proporção original, a menos que seu pipeline faça recortes deliberados. Armazene uma soma de verificação e um ID interno de ativo. O base64 aumenta o tamanho da solicitação, portanto evite codificar repetidamente versões mestras excessivamente grandes quando uma versão derivada com dimensões adequadas preserva todos os detalhes visíveis.

Escreva um prompt consciente da preservação

Um bom prompt informa ao Veo o que acontece e o que deve permanecer estável. Use esta ordem reutilizável:

Plano de acompanhamento em médio close. O motociclista de cabelos prateados, vestindo a jaqueta cor açafrão, conduz a motocicleta azul-cobalto fosca ao longo de uma estrada costeira molhada ao amanhecer. Preserve seu rosto, o contorno do corte de cabelo curto, os óculos com viseira âmbar, os painéis da jaqueta, a geometria do corpo da motocicleta, a quantidade de rodas e o acabamento azul-cobalto. A névoa do oceano se move naturalmente; a câmera acompanha em paralelo, sem girar em órbita. Áudio nativo de vento, pneus e ondas distantes; sem diálogo, sem texto, sem logotipo.Nomeie referências com base em traços visíveis, não em nomes de arquivos. Mantenha uma única ação principal e um único movimento de câmera por plano de oito segundos. Comandos contraditórios, como “câmera fixa” e “órbita rápida”, geram um problema de coordenação que nenhuma imagem de referência consegue resolver. O guia de prompting de imagem para vídeo apresenta um padrão compacto sujeito-ação-câmera-preservação que você pode reutilizar.

Envie uma solicitação Veo 3.1

Crie referências de ativos no JavaScript

Com a versão atual @google/genai SDK, represente cada imagem preparada como um objeto contendo imageBytes e mimeType, então envolva-o com referenceType: 'asset'. O SDK lê a chave da API do seu ambiente; mantenha-a no servidor, nunca no JavaScript do navegador.

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const assets = [riderImage, motorcycleImage, glassesImage].map((image) => ({
  image,
  referenceType: 'asset',
}));

let operation = await ai.models.generateVideos({
  model: 'veo-3.1-generate-preview',
  prompt,
  config: {
    referenceImages: assets,
    aspectRatio: '16:9',
    durationSeconds: 8,
    resolution: '720p',
  },
});

Os nomes dos campos podem diferir entre as superfícies Gemini API e Vertex AI, portanto, fixe a versão do SDK e valide-a contra a documentação oficial do ponto de extremidade que você realmente implantar. Não copie a estrutura JSON de um wrapper de terceiros para um ponto de extremidade do Google. Registre um manifesto de solicitação com dados sensíveis removidos, em vez da carga completa em base64.

Use resolução 720p na primeira etapa de aceitação. Após a validação de identidade, movimento, câmera e áudio, repita a configuração aprovada na resolução exigida para entrega. Se sua aplicação rotear solicitações entre provedores, o guia agregador versus API direta explica por que um registro de tarefa normalizado é mais confiável do que a memória de interface específica de cada provedor.

Consulte, baixe e armazene a saída

A geração de vídeos Veo é assíncrona. A chamada inicial retorna uma operação de longa duração, não o arquivo MP4 finalizado. Consulte continuamente pelo nome da operação com um intervalo razoável, interrompa ao atingir um tempo limite definido e persista a ID da operação para que um reinício do worker possa retomá-la, em vez de submeter um trabalho duplicado.

while (!operation.done) {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  operation = await ai.operations.getVideosOperation({ operation });
}

const generated = operation.response.generatedVideos[0];
await ai.files.download({
  file: generated.video,
  downloadPath: `outputs/${jobId}.mp4`,
});

Atualmente, o Google retém vídeos gerados em seus servidores por dois dias, portanto, baixe-os imediatamente para um armazenamento sob seu controle. Verifique se o arquivo existe, possui comprimento não nulo, é decodificável como vídeo e corresponde à duração esperada. Salve um quadro de destaque (poster frame) para revisão, mas nunca trate esse quadro como prova de que todo o movimento está correto.

Exemplo de vídeo cinematográfico Veo 3.1 para inspeção completa do clipe

Assista ao clipe completo para avaliar continuidade de identidade, ambiente, câmera e áudio. Um arquivo em movimento revela falhas que um único quadro atraente pode ocultar.

Valide a consistência e trate falhas

Revise com uma grade de aceitação fixa

Inspeccione cada saída em velocidade normal e novamente durante o movimento mais complexo. Registre aprovação, revisão ou rejeição com base nos mesmos critérios sempre:

Essa composição alternativa altera o horário e o enquadramento, mas preserva os mesmos pontos de ancoragem de continuidade. Use esse tipo de quadro para avaliar se a identidade do ativo sobrevive a uma mudança de cena.

Se todas as saídas perderem a mesma característica, é provável que a hierarquia de referências ou prompt esteja incorreta. Se as falhas variarem aleatoriamente, mantenha as entradas fixas e execute novamente antes de reescrever tudo. Se a composição precisar terminar exatamente em uma imagem projetada, mude para image mais lastFrame, em vez de adicionar mais linguagem de preservação a referenceImages.

Saída de movimento de produto Seedance para comparar geometria e comportamento controlado da câmera

Este é um modelo e tipo de plano diferentes, incluído como exemplo real de revisão de movimento, não como referência de desempenho para Veo. Aplique o mesmo critério de geometria e câmera.

Diferencie erros do provedor de falhas criativas. Autenticação, cota, MIME inválido, configuração não suportada, filtragem de segurança, tempo limite e clipe concluído mas inutilizável exigem respostas distintas. Tente novamente automaticamente apenas erros transitórios de transporte ou de serviço. Um prompt rejeitado ou um resultado visual inadequado devem retornar à revisão humana, não entrar em um ciclo pago infinito.Antes da exportação final, confirme a cadência de entrega com o guia de taxa de quadros para vídeos de IA, pois a geração a 24 fps e as configurações de entrega na plataforma estão relacionadas, mas não são decisões intercambiáveis.

Incorpore-o a um fluxo de trabalho Seedance Agent

A API bruta Veo é adequada quando um desenvolvedor já gerencia o armazenamento de ativos, a versão de prompts, a sondagem de operações, aprovações e políticas de repetição. O Seedance Agent é útil quando a tarefa real abrange mais de uma chamada: transformar um briefing em uma lista de planos, atribuir papéis de referência, escolher um modelo compatível por plano, analisar as saídas reais e executar novamente apenas o segmento com falha.

Para a sequência do motociclista, um agente pode registrar o retrato, a motocicleta e os óculos uma única vez; criar um plano de acompanhamento costeiro e um encerramento ao “horário azul” como trabalhos separados; manter suas regras de preservação alinhadas; e disponibilizar ambos os clipes para aprovação. A API permanece como camada de geração, enquanto o agente mantém o estado produtivo. Isso reduz solicitações duplicadas acidentais e impede que uma edição tardia do prompt altere silenciosamente o conjunto canônico de ativos.

Meça o custo por segundo aprovado, não por solicitações concluídas. Compare o Veo 3.1 com outras rotas quanto à estabilidade de identidade, finalizações utilizáveis, tempo de revisão e número de repetições, usando a comparação entre Seedance 2.5 e Veo 3.1. O objetivo não é forçar todos os planos por meio de um único modelo, mas entregar uma sequência consistente com o menor número possível de revisões evitáveis.

Conclusão

Uma integração confiável da API de imagens de referência Veo começa com a escolha do modo de controle adequado, a preparação de até três referências de ativos coerentes, a redação de um único prompt claro sobre movimento e preservação, o envio de uma solicitação válida do Veo 3.1, a persistência da operação de longa duração, o download antes da expiração do período de retenção e a revisão completa do clipe com uma rubrica fixa. Mantenha as novas tentativas transitórias da API separadas das repetições criativas e mude para interpolação entre o primeiro e o último quadro quando os pontos finais exatos forem mais importantes do que a orientação flexível de ativos; quando o projeto exigir planejamento de planos, referências compartilhadas, roteamento de modelos, aprovações e repetições seletivas em torno da chamada da API, inicie o fluxo de trabalho com Seedance Agent →