ai-product-video

AI Product Video (Vídeo de Produto com IA)

Divisão de trabalho principal:

• Modelo 3D ou foto do produto: Decide onde o produto está, seu tamanho, como se move e quando muda.
• Modelo de imagem: Responsável por fazer a imagem parecer real.
• Modelo de vídeo: Responsável por fazer a imagem se mover.
• Código: Usa os fatos do produto e o modelo 3D como régua para medir cada imagem e vídeo gerado pela IA. Se não passar, não gasta dinheiro.

Edição, legendas, anotações e áudio são camadas de overlay orientadas a dados. Para alterar uma palavra, não é necessário regenerar as imagens.

Este método vem de um projeto real: um vídeo de demonstração para investidores de um produto de hardware inteligente. A rota foi alterada quatro vezes até funcionar. Uma análise anônima está em examples/case-study.md. Abaixo está a versão genérica após o sucesso, aplicável a vídeos explicativos e anúncios.

Por que não seguir cegamente o fluxo de trabalho de séries animadas com IA

O fluxo de trabalho de séries animadas com IA é: roteiro → storyboard → biblioteca de ativos → quadros estáticos → modelo de vídeo anima → narração e edição. Ele não usa modelo 3D, e o público tolera imprecisões visuais, então a imagem gerada pela IA é a resposta correta.

Um vídeo de produto vende "este produto tem essa aparência e é usado assim". Se a orientação da interface, o logotipo ou a posição da luz estiverem errados, o vídeo está mentindo. Portanto:

• Mantenha a estrutura: Ativos primeiro, estático antes do movimento, escolha o modo por cena, prompt apenas para mudanças, teste em baixa resolução, verifique quadro a quadro.
• Altere apenas uma coisa: A resposta correta não é a imagem gerada pela IA, mas sim os fatos do produto + modelo 3D (ou foto real / desenho CAD).

Outra lição: os pixels renderizados em 3D não devem ir diretamente para o vídeo final, não importa o quão detalhados sejam, eles sempre terão um aspecto CG. Deixe o modelo de imagem redesenhar sobre a imagem base 3D e use esta imagem como o primeiro e o último quadro do vídeo. Só assim a sensação de realidade aparece.

Primeiro passo: Iniciação, faça estas 8 perguntas primeiro

Detalhes e como perguntar ao usuário estão em references/01-intake.md.

1. Estimativa de tempo: Na primeira resposta, informe aproximadamente quantos minutos ou dias, e a que horas estará pronto, listado por etapa, incluindo as etapas que o usuário precisa fazer pessoalmente; atualize imediatamente em caso de atraso.
2. Tipo de vídeo e local de exibição: Vídeo explicativo, anúncio de marca, vídeo curto vertical, vídeo de e-commerce ou curta para apresentação, onde será exibido, duração e proporção de tela. Escolha a abordagem de acordo com references/02-formats.md; uma produção pode gerar múltiplas versões de entrega.
3. O público é interno ou público?: Interno e investidores podem ver diagramas de explosão, vistas transparentes e estrutura interna; versões publicadas não mostram estruturas internas nem nomes de componentes. Isso determina quais ângulos podem ser filmados.
4. Formulário de confirmação de fatos do produto (templates/product_facts.md): Qual componente realiza cada função, de onde ela vem, como aparece na cena, como não deve aparecer, se é um objetivo de design ou já implementado, se pode ser divulgado publicamente. Itens inferidos devem ser marcados como "pendente de confirmação" até que o responsável confirme.
5. Referência de qualidade: Peça ao usuário um vídeo de referência. Meça seu nível de movimento e processo de produção. Aprenda apenas a qualidade visual, não a estrutura.
6. Ferramentas disponíveis para o usuário:
   • Modelo de imagem: Apenas assinatura, precisa ser desenhado manualmente pelo usuário, ou tem API que pode ser chamada por script?
   • Modelo de vídeo: Conta de API (pode ser chamada por script) ou membro de site/app (apenas geração manual: use pacote de vídeo manual, verifique primeiro os termos de uso comercial, não presuma que pode fazer upgrade do rascunho)?
   • Existe um modelo 3D ou CAD do produto? Se não, existe uma amostra física ou qualquer imagem renderizada? Sem 3D, siga a "rota sem 3D" (references/03-previs.md seção 10).
7. Orçamento e cobrança: Fórmula de preço, pacotes, valor real dos vouchers, saldo da conta, limite total. Antes de geração em massa e upgrade para alta definição, peça ao usuário para verificar o saldo.
8. Teste pequeno antes de definir a rota: Gere dois rascunhos em baixa resolução para a mesma cena: um usando o modelo 3D ou foto do produto como primeiro quadro, e outro usando o keyframe realista gerado pelo modelo de imagem como primeiro quadro. Por alguns reais e alguns minutos, você já vê a diferença.

Convenção da pasta do projeto

Todos os scripts usam a pasta especificada por --project como raiz (o diretório atual é o padrão). Para novos projetos, crie esta estrutura:

<project>/
  .env                    Chaves (ARK_API_KEY, etc.), não entrar no repositório, não aparecer no chat
  brief/                  creative_brief.md, product_facts.md, benchmark.md, budget.md, decisions.md, feedback_brief.md, claims.md, licenses.md
  shots/shot_list.json    Lista de cenas, única fonte da verdade para a linha do tempo
  shots/prompts/<id>.txt  Prompts de vídeo para cada cena (adicione número de versão ao alterar, mantenha a antiga)
  plates/<id>/            Imagens base 3D, máscaras, coordenadas da câmera (sem 3D, coloque imagens de referência do produto)
  packs/                  look_bible.txt (configuração unificada, única fonte), pacote de geração manual de imagens, pacote de geração manual de vídeo
  keyframes/keyframes.json  Lista de keyframes (master, primeiro/último quadro, ordem de upload)
  keyframes/raw/          Imagens originais do modelo de imagem
  keyframes/norm/         Keyframes redimensionados para o tamanho de saída
  footage/                Materiais filmados, gravações de tela, capturas de tela reais, etc. que não são gerados (opcional)
  gen/                    Saída do modelo de vídeo e video_log.jsonl (registro de chamadas e gastos)
  qc/                     Imagens de grid quadro a quadro, relatórios Gate K / Gate V
  edit/                   edl.json, captions.json, callouts.json, approved_drafts.json, approved_bridges.json
  renders/                Vídeo sem áudio da saída do editor e .timeline.json (local de saída padrão do edit.py)
  sound/                  Faixas separadas de música e efeitos sonoros, cue sheet, janela de mixagem
  deliver/                Vídeos finais (versão pública e versão interna separadas)
  work/                   Scripts e fluxos de trabalho do próprio projeto (gerar EDL, pacote de imagens, verificação), cada resultado é escrito em disco

Copie os templates de templates/ para as pastas correspondentes: creative_brief.md, product_facts.md, benchmark.md, budget.md, feedback_brief.md, claims.md, licenses.md para brief/, decision_list.md como brief/decisions.md; shot_list.json para shots/; keyframes.example.json como keyframes/keyframes.json; o bloco de código prompts/look_bible.md preenchido como packs/look_bible.txt; sfx_cue_sheet.md para sound/; os cinco *.example.json (edl, captions, callouts, approved_drafts, approved_bridges) remova .example e coloque em edit/.

A proporção de tela é escrita nos dados, não em comandos:

• Geração de vídeo: A proporção das tarefas de primeiro/último quadro segue a do primeiro quadro (primeiro unifique os keyframes com scripts/qc/normalise_keyframes.py --size 1080x1920); no modo de referência, adicione --aspect 9:16 para vertical.
• Edição: Em edit/edl.json, escreva "size": [1080, 1920], depois uv run scripts/edl_editor/edit.py --project <project> --edl edit/edl.json --dry organiza na vertical; --res 480 gera uma prévia pequena na mesma proporção; --size WxH gera em outra proporção.
• Feed vertical: Em edit/captions.json, o style deve ser "preset": "feed_safe"; legendas e texto pequeno nos créditos finais ficam dentro da área segura conservadora; --dry verifica item por item.

No primeiro dia, execute git init e adicione .env, gen/, renders/, .cache/ ao .gitignore. Para cada tipo de dados, apenas um arquivo é a fonte:

• Aparência do produto: Arquivo de especificações ou modelo 3D master; configuração unificada: packs/look_bible.txt;
• Linha do tempo: shots/shot_list.json;
• Legendas: edit/captions.json;
• Edição: edit/edl.json;
• Cenas aprovadas: edit/approved_drafts.json, edit/approved_bridges.json;
• Alegações e licenças: brief/claims.md, brief/licenses.md;
• Feedback do usuário: brief/feedback_brief.md.

Pipeline

Duas trilhas paralelas: trilha visual e trilha de áudio. O áudio não deve esperar o vídeo ser atualizado para HD. Comece a trabalhar assim que a estrutura de edição estiver definida.

#	Etapa	Saída	Revisão do usuário	Verificação automática / Registro	Detalhes
1	Iniciação e fatos	Brief criativo, formulário de confirmação de fatos do produto, lista de entregas	Confirmar fatos, tipo de vídeo, orçamento	—	01, 02
2	Criatividade e lista de cenas	Estrutura, batidas, lista de cenas (cada cena: posição da câmera, ação, efeito, estado do produto, modo, transição, legenda, efeito sonoro)	Definir estrutura e direção do texto	Verificar se a duração e o tempo de leitura cabem	02, rulebook §1
3	Pré-visualização e imagens base	Modelo 3D master, contrato de imagem base para cada keyframe, vídeo de pré-visualização em cinza quando necessário; sem 3D, use imagens de referência do produto	Ver visão geral das imagens base	Verificar orientação, cabos, intersecções de malha a partir de cada posição real de câmera	03
4	Definição do master	Master do produto, master da cena, design de personagem (ativos primeiro, antes de todos os keyframes de cena)	Revisar cada um com checkpoints	—	04 §2, §3
5	Keyframes	Um pacote de imagens para cada um, ou chamada de API por script; redimensionar para tamanho uniforme	Desenhar manualmente ou revisar imagens	Gate K (script do projeto): contorno, proporção, estado do efeito, consistência de escala, arquivos duplicados	04
6	Rascunho de vídeo	Rascunho em 480p	Usuário ativa e paga; ver saldo antes de lote; ver rascunho	Simulação de condições de rejeição (incluindo verificação de prompt); imagens de grid a cada 0,25s; Gate V (script do projeto)	05
7	Revisão e registro	edit/approved_drafts.json, edit/approved_bridges.json, corte grosseiro	Dar feedback, numerado e escrito no brief	Aprovação manual vincula impressão digital do arquivo	05 §13
8	Edição e legendas	Prévia EDL: transições, cenas de transição com IA, legendas, anotações, cartões de abertura e encerramento	Alterar texto e ordem	--dry verifica intervalos e tempo de leitura; revisão de quadros estáticos de legendas	06
9	Upgrade para HD	Cenas aprovadas são atualizadas para 1080p sem alterações	Liberar após texto e ordem finalizados; ver saldo primeiro	Consistência de duração e quadros intermediários	05 §6
S1	Design de som (paralelo a 8, 9)	Seleção e licenciamento de música, cue sheet de efeitos sonoros, som do produto, narração quando necessário	Selecionar música (enviar arquivos reproduzíveis), ouvir transições	Registro de licenciamento	07
S2	Mixagem	Trilha de áudio final balanceada	Ouvir o vídeo final	Medir dB de "efeito menos música" por janela de tempo; alvo de loudness	07
10	Entrega	Master, versão para compartilhamento (até 30 MB), versões para cada plataforma, versões cortadas de 15/6 segundos	Definir texto de abertura, solicitar vídeo final	Duração, fluxos de áudio e vídeo, loudness, imagem do keyframe	08
11	Multilíngue	Um arquivo de texto gera legendas e EDL paralelos	Definir texto	Versão original permanece pixel a pixel inalterada; caracteres residuais do idioma original = 0	08
12	Verificação de conformidade final	brief/claims.md, brief/licenses.md, marcação de IA	Assinar	Verificação de lista de palavras + verificação frase a frase dos fatos do produto	09

As 12 regras mais importantes

As 139 regras completas estão em references/rulebook.md.

1. Escreva o formulário de iniciação primeiro: Tipo de vídeo, público (interno ou público), plataforma, duração, proporção de tela, depois fale sobre criatividade.
2. Fatos do produto escritos e confirmados primeiro; uma correção corrige todos os downstream (3D, imagens base, prompts de imagem, prompts de vídeo, legendas, anotações, brief) de uma vez, depois pesquise globalmente por palavras residuais.
3. 3D apenas define a posição, os pixels finais são desenhados pela IA; para cada cena, pergunte "de onde vêm os pixels finais?".
4. Keyframes de IA devem ser usados como primeiro e último quadro para conduzir a cena, não apenas como uma das muitas imagens de referência.
5. Cada pixel alimentado ao modelo de vídeo será copiado: Pré-visualização em cinza deve ser cinza uniforme e com ruído reduzido; não coloque imagens de ângulos diferentes no pacote de referência; a imagem de referência em si deve estar correta.
6. Prompts de vídeo devem ser escritos como um roteiro segundo a segundo, os números derivados do modelo 3D ou da lista de cenas, não escritos à mão; escreva apenas as mudanças, não repita a descrição da aparência.
7. Efeitos devem ser escritos como a câmera os filmaria, e deixe claro "o que não é"; para uma luz constantemente acesa, escreva "brilho constante"; use padrões visíveis a olho nu para verificar a quantidade.
8. Gastos são divididos em dois níveis: Primeiro, passe pela verificação gratuita e saia com um rascunho em 480p; só então atualize para HD exatamente como está, e verifique o saldo antes.
9. Veja o vídeo original quadro a quadro: O modo primeiro/último quadro pode fazer crossfade escondido no meio; a revisão independente deve ver o vídeo original gerado.
10. Legendas, anotações e áudio estão todos na camada de edição, gerados a partir dos dados da linha do tempo; alterar texto, reordenar ou atualizar para HD não requer regenerar as imagens.
11. Conformidade em duas etapas: Primeiro, verifique a lista de palavras (palavras extremas, alegações de eficácia, médicas, números); depois, verifique frase a frase com os fatos do produto para encontrar "funções implícitas". O padrão para marcação de IA é marcar uma vez na tela de abertura (pelo menos cerca de 2 segundos), explicar uma vez no texto pequeno dos créditos finais, e adicionar a declaração de IA da plataforma; não coloque um logotipo constante, a menos que a plataforma exija.
12. Cada feedback do usuário é numerado e escrito no brief, e todos os agentes e a revisão final o consultam. Conversas longas podem ser compactadas, os arquivos não.

Colaboração com o usuário

• Tempo: Dê uma estimativa primeiro; para tarefas longas sem saída visível, relate proativamente o estágio atual, a hora da última atividade e a nova hora estimada.
• Quando for a vez do usuário agir, entregue tudo de uma vez: Arquivos de instrução completos, materiais que podem ser abertos ou reproduzidos diretamente, enviados para o celular (arquivo único de até 30 MB). Diga ao usuário em qual pasta colocar o master.
• Entenda o modo de trabalho: "Apenas analise" significa apenas analise; "não pare no meio" significa vá até a entrega; "última rodada" significa pule as audições intermediárias.
• Conclusão primeiro: Se o usuário perguntar "precisa refazer tudo?", a primeira frase dá a conclusão, depois explica os motivos e, finalmente, lista os pontos que precisam da aprovação do usuário.
• Segurança:
  • Não leia, não exiba, não solicite chaves (apenas coloque em .env);
  • Não crie contas, não insira senhas ou informações de pagamento;
  • Ao concordar com termos, pagar, ativar, recarregar, pare antes do botão, explique os custos e deixe o usuário clicar;
  • Pergunte antes de baixar arquivos.
• Tarefas longas:
  • Antes de começar, peça ao usuário para conectar a energia, definir o sistema para "nunca" dormir e solicitar para manter o computador ativo;
  • Fluxos de trabalho e processamento em lote devem poder ser retomados a partir do disco;
  • Separe o envio da consulta dos resultados;
  • Renderização 3D deve abrir apenas um processo por vez.

Detalhes em references/10-working-with-user.md.

Publicação

Para conteúdo público, incluindo anúncios, redes sociais, imagens de apresentações públicas:

• Não coloque diagramas de explosão, vistas transparentes, ou cenas que mostrem a estrutura interna; não escreva nomes de componentes internos ou princípios de funcionamento;
• Em postagens de redes sociais, não mencione produtos de IA específicos (escreva "modelo de imagem de grande escala", "modelo de vídeo", "software 3D");
• Não divulgue gastos;
• Escreva sobre os desafios como problemas gerais de fluxo de trabalho, não como experiências pessoais;
• Adicione a declaração de geração por IA exigida pela plataforma.

Veja references/09-compliance.md para mais detalhes.

Ferramentas

Todos os scripts são executados com uv run. As dependências estão no bloco PEP 723 no início de cada script. ffmpeg vem do imageio-ffmpeg.

Script	Uso
scripts/edl_editor/edit.py	Gera vídeo a partir do EDL: cartões, crossfade, tela preta, flare, whip pan, cenas de transição com IA, legendas, anotações, logotipo; suporta 16:9, 9:16, 1:1; --dry simula, gera timeline.json. Use make_demo.py para gerar um projeto de demonstração com um clique
scripts/edl_editor/typeset.py	Mecanismo de layout de legendas e cartões: hierarquia chinês/inglês, ajuste de pontuação, zona segura, fallback de fontes entre plataformas; --specimen pode verificar fontes do sistema
scripts/video_api/seedance.py	Cliente Seedance da Volcano Engine: modos de primeiro/último quadro, imagem de referência, rascunho e upgrade para HD, consulta retomável, estimativa de custo e registro, --dry não usa rede, apenas faz verificações (incluindo verificação de prompt); também pode ser usado como modelo para escrever adaptadores para outros modelos de vídeo
scripts/audio/mix.py	Balanceia faixas separadas de música e efeitos sonoros por janela de tempo, mede diferença de dB, limita e normaliza loudness em duas passagens, depois sintetiza com o vídeo
scripts/qc/strip.py	Extrai um quadro a cada 0,25s e monta uma imagem longa, desenha curvas de movimento e brilho, marca cortes secos, saltos e congelamentos
scripts/qc/contact_sheet.py	Grid de imagens com rótulos, usado para revisar imagens base, keyframes e rascunhos
scripts/qc/normalise_keyframes.py	Keyframes raw → norm: corta os quadros da cena para a proporção de saída, master e imagens de referência são apenas redimensionados, sem cortes, ampliações e cortes bruscos geram aviso
scripts/qc/lint_prompts.py	Varredura de palavras proibidas em prompts de vídeo (incluindo palavras proibidas relacionadas a mecanismos do produto); gera erro se nenhum arquivo for encontrado

Scripts não incluídos, que o projeto deve escrever em work/: Decisão do Gate K e Gate V (seedance.py não lê relatórios Gate K; "sem relatório, não envie" é garantido pela etapa de envio do projeto), geração do pacote de imagens (keyframes.json → packs/), shot_list.json → EDL e rascunho de legendas. Requisitos em 04, 05, 06 e templates/prompts/keyframe_pack.md.

Instruções de uso estão no README de cada diretório. As capacidades, preços e limitações dos modelos mudam rapidamente; verifique a documentação oficial antes de usar. As "Notas do modelo" no final de cada arquivo de referência indicam a data da verificação.

Quando ler cada arquivo

Arquivo	Quando ler
references/01-intake.md	No primeiro dia de um novo projeto
references/02-formats.md	Ao definir tipo de vídeo, duração, proporção, estrutura, ou ao fazer anúncios e vídeos verticais curtos
references/03-previs.md	Antes de montar a pré-visualização 3D ou imagens base; quando não houver modelo 3D
references/04-keyframes.md	Ao escrever pacotes de imagens, definir configuração unificada, verificar keyframes
references/05-video-gen.md	Ao escrever prompts de vídeo, escolher modo de geração, enviar, revisar rascunhos, atualizar para HD
references/06-edit-type.md	Edição, transições, legendas, anotações, cartões de abertura e encerramento
references/07-sound.md	Seleção de música, efeitos sonoros, narração, mixagem
references/08-delivery.md	Entrega, versões para cada plataforma, versões cortadas, multilíngue
references/09-compliance.md	Antes de escrever qualquer texto na tela ou narração; antes da publicação pública
references/10-working-with-user.md	Colaboração com usuários que não programam, tarefas longas, limites de segurança, problemas de ambiente
references/rulebook.md	Quando estiver em dúvida em uma etapa, consulte o conjunto correspondente
references/pitfalls.md	Quando surgir um problema, primeiro procure pelo sintoma
templates/	Copie para o projeto ao começar, preencha e use
examples/case-study.md	Para ver como um projeto completo se desenrolou