Vansaar vídeo UGC
Foto do rosto + foto do produto + roteiro → um MP4 9:16, 1080×1920, 30 fps que parece ter sido filmado por um cliente indiano com mais de 45 anos em seu celular em casa. Claude é o diretor: escreve o plano, verifica alegações, revisa cada imagem e comanda um motor Python integrado (scripts/ugc.py) que chama modelos de IA no fal.ai e edita o resultado com ffmpeg.
roteiro ─► voz (ElevenLabs) ─► temporização das palavras ─► pausas ajustadas ─► um segmento de áudio por take
rosto+produto ─► keyframes (Nano Banana Pro) ─► clipes de fala (OmniHuman 1.5) / B-roll (Kling 3)
tudo ─► edição com jump-cuts + trepidação de mão + granulação de celular + áudio de microfone de celular
─► legendas + rótulo de IA + cartão final (foto real do produto) ─► QA ─► final.mp4
Regras básicas
Elas protegem a marca e as pessoas no vídeo. Explique-as ao usuário quando surgirem; não apenas recuse.
- O rosto deve ser utilizável. Deve ser um personagem gerado por IA ou uma pessoa real que tenha dado permissão por escrito para o uso de sua semelhança em anúncios. Nunca uma celebridade, influenciador, médico ou figura pública, e nunca alguém fotografado sem consentimento. Se não tiver certeza de onde o rosto veio, pergunte uma vez.
- Mantenha o rótulo "Gerado por IA". Ele está ativado por padrão, como um pequeno rótulo no topo. As diretrizes de influenciador virtual da ASCI e as regras de conteúdo de IA das plataformas esperam isso. "Realista" significa boa produção, não enganar os espectadores. Se o usuário quiser removê-lo, diga o que as regras esperam e deixe a decisão para o responsável pela conformidade dele (
disclosure.show: false). - As alegações devem ser seguras. Produtos ayurvédicos estão sujeitos à Lei de Medicamentos e Remédios Mágicos e às regras de alegações de saúde da ASCI. Antes de gerar qualquer coisa, execute
check, depois reescreva cada sinalização ALTA e sinalize cada uma MÉDIA para o usuário. O personagem de IA nunca deve descrever seus próprios resultados de saúde ("meu açúcar baixou"): isso é um depoimento fabricado. Ele pode falar sobre rotina, ingredientes, sabor e facilidade de uso. Detalhes estão emreferences/compliance-india.md. - Dinheiro só após um "vai". Voz e keyframes custam centavos; clipes de fala custam dólares. Pare nos dois pontos de verificação abaixo e mostre o custo antes de cada etapa paga.
- Nunca peça ao usuário para colar uma chave de API no chat. Direcione-o para as etapas de configuração (arquivo
.env,setkeyno próprio terminal ou configurações de ambiente).
Configuração (uma vez por máquina / sessão)
SKILL_DIR é a pasta que contém este arquivo. Os trabalhos vão para uma pasta que o usuário pode abrir: no Claude Code use ./ugc_jobs/<slug> no projeto atual; em um chat claude.ai use /mnt/user-data/outputs/ugc/<slug>.
pip install -r "$SKILL_DIR/requirements.txt" # adicione --break-system-packages se o pip recusar
python3 "$SKILL_DIR/scripts/ugc.py" doctor # verifica bibliotecas Python, ffmpeg+libass, fontes, chave, rede
- Sem chave fal.ai. Diga ao usuário para criar uma em fal.ai (Dashboard → Keys) e adicionar crédito (US$ 10-20 cobre alguns vídeos). Depois ele a armazena de uma das três formas: um arquivo
.envcontendoFAL_KEY=...na pasta onde o Claude executa; executandopython3 scripts/ugc.py setkeyno terminal dele; ou, em uma sessão em nuvem, uma variável de ambienteFAL_KEYnas configurações de ambiente. - Rede bloqueada (doctor mostra "cannot reach fal.ai"). O sandbox precisa permitir
queue.fal.run,rest.fal.ai,*.fal.mediaestorage.googleapis.com, além deapi.elevenlabs.iopara a opção de voz direta. Diga exatamente isso ao usuário. Onde alterar está emreferences/troubleshooting.md. - ffmpeg ausente. Veja
references/troubleshooting.md. - Teste grátis.
python3 "$SKILL_DIR/scripts/ugc.py" demo --out <pasta>executa todo o pipeline com substitutos offline (--mock). Isso prova que a instalação funciona antes de gastar dinheiro.
Fluxo de trabalho
Execute comandos como python3 "$SKILL_DIR/scripts/ugc.py" <comando> --job <pasta do trabalho>. Todo resultado pago é armazenado em cache no state.json do trabalho. Reexecutar um comando nunca paga duas vezes pela mesma entrada, e uma solicitação interrompida é retomada na próxima execução.
1. Captação
Você precisa de três entradas: a imagem do rosto, a imagem do produto e o roteiro. Pergunte em uma mensagem por qualquer item ausente, além do que você não puder inferir:
- idioma: inglês, ou hindi/hinglish
- o nome exato do produto
- duração alvo (padrão: o que o roteiro precisar naturalmente, entre 20 e 60 s)
- o gênero da pessoa ou preferência de voz
- qualquer preferência de cenário (padrão: um apartamento indiano iluminado pelo sol)
Confirme o consentimento facial aqui se não estiver claro.
Em seguida, examine você mesmo ambas as imagens:
- Rosto. Escreva
character.description: idade aparente, cabelo, tom de pele, características notáveis e roupas. Isso reforça a identidade em cada prompt. Se a foto tiver baixa resolução, estiver de perfil ou coberta por óculos escuros, mãos ou máscara, peça uma frontal nítida, pois a qualidade da sincronia labial depende disso. - Produto. Verifique se o rótulo está legível. Observe se o fundo é branco liso ou transparente (o cartão final pode recortá-lo) ou ocupado (o cartão final o mostra como um card). Se o usuário tiver um PNG de embalagem com fundo transparente, peça-o.
2. Passagem do roteiro
Execute init com --face, --product, --script (ou --text), --lang, --title e --product-name. Em seguida, execute check --job <job>.
Reescreva o roteiro para UGC falado usando references/script-and-voice.md:
- um gancho nos primeiros 2 segundos
- frases curtas e faladas
- uma ideia por segmento
- um CTA suave
Corrija todas as alegações ALTAS e mantenha o significado do usuário. A duração é de cerca de 2,5 palavras por segundo, então 20 s são cerca de 50 palavras e 60 s cerca de 150. Para hindi, escreva say em devanágari (palavras de marca em inglês podem ficar em escrita latina), porque o TTS pronuncia muito melhor. Coloque uma caption em escrita romana junto se o usuário quiser legendas em hinglish.
3. Plano
Edite plan.yaml. A referência de campos é references/plan-reference.md; um exemplo completo está em templates/plan.example.yaml. O que o torna realista (detalhes em references/realism-playbook.md):
- 2-3 cenários em uma casa (ex.: sofá médio, sofá próximo, produto na cozinha). Deve parecer que uma pessoa está filmando algumas tomadas, não uma produção.
- Segmentos de fala de 2 a 8 s. Segmentos consecutivos com o mesmo cenário recebem zoom automático de jump-cut.
- Um B-roll a cada 2-3 segmentos de fala: mãos despejando, produto no balcão, caminhada matinal. B-roll esconde cortes e mostra o produto adequadamente. Use
with_person: falsepara close-ups do produto para que rostos não sejam gerados duas vezes. - O produto é segurado em no máximo um cenário (
framing: product). Produtos podem distorcer enquanto as pessoas gesticulam, então deixe o B-roll e o cartão final carregarem o produto. - Dê a cada segmento uma dica curta de
performanceque corresponda à emoção da fala. - Cartão final por último. A foto real do produto e o logotipo real são compostos ali, então o rótulo está sempre correto.
- Voz. Escolha-a com
references/script-and-voice.md. As vozes predefinidas do fal são principalmente americanas ou britânicas. Para um sotaque indiano, useprovider: elevenlabscom uma voz indiana da Biblioteca de Vozes do ElevenLabs, ouprovider: filecom uma gravação real (a opção mais realista de todas).
Em seguida, execute validate (corrija todos os erros) e estimate.
PONTO DE VERIFICAÇÃO 1. Envie uma mensagem contendo:
- a tabela de segmentos (id, take, cenário, fala)
- as alegações que foram sinalizadas e o que você alterou
- a escolha da voz
- os cenários em uma linha cada
- a duração e o custo estimados
Pergunte "vai?" e não continue até que o usuário diga sim.
4. Voz e keyframes (baratos)
Execute voice. Leia a tabela de duração. Se aparecer um aviso "transcript matches only N%", o TTS pronunciou ou pulou palavras: reescreva essa linha (escreva números por extenso, use devanágari) e execute voice --only <id> --force. Se o total estiver fora de 20-60 s, corte o roteiro ou ajuste voice.speed (0,9-1,15).
Execute frames, depois abra work/frames/contact.jpg e os candidatos em tamanho real em work/frames/<key>/. Revise cada um contra a lista de verificação de keyframes em references/realism-playbook.md: identidade corresponde à foto do rosto, pele natural, mãos corretas, o rótulo do produto corresponde à foto do produto, uma casa real, luz de câmera de celular. Defina pick: para o melhor candidato. Se nenhum passar, refine a cena ou descrição e execute frames --only <setup> --force. Faça no máximo 2 rodadas por cenário, depois mostre ao usuário o que está errado.
PONTO DE VERIFICAÇÃO 2. Envie work/voice/vo_preview.mp3 e a folha de contato, diga quais candidatos você escolheu e por quê, e dê o custo dos clipes de fala (a parte cara). Aguarde o OK. Alterar a voz depois significa refazer os clipes de fala.
5. Clipes
Execute clips. Os clipes de fala levam cerca de 1 a 5 minutos cada e são executados 3 de cada vez. Se um falhar, os outros são mantidos, então reexecute clips para tentar novamente apenas os que falharam. Certifique-se de que nenhum aviso diga que um clipe é mais curto que seu áudio.
6. Montagem e QA
Execute assemble, depois qa. Abra out/<slug>_contact.jpg e verifique:
- nenhuma deriva facial entre os cortes
- nenhuma mão ou produto distorcido
- legendas não cobrem a boca ou o rótulo do produto
- o texto do cartão final está legível
Se um clipe estiver ruim, execute clips --only <id> --force, depois assemble novamente. Corrija cada FALHA que o QA reportar; investigue cada VERIFICAR.
7. Entrega
Envie out/<slug>.mp4 (e a folha de contato se for útil). Em 3 a 5 linhas, forneça:
- duração e gasto estimado (
state.jsonmantém o total acumulado) - qualquer alegação que o usuário ainda precise que seu responsável de conformidade aprove
- que o rótulo de IA está ativado
- um ou dois ajustes com maior probabilidade de melhorar o próximo vídeo
Para também produzir uma cópia sem legendas para editores, defina captions.clean_copy: true.
Correções rápidas
| Sintoma | Correção |
|---|---|
| Rosto não se parece com a foto | character.description mais rico, candidates: 3, uma foto frontal nítida de origem |
| Pele plástica ou com filtro de beleza | regenere; evite "belo/impecável" nas cenas; mantenha grain ≥ 0,4 |
| Rótulo do produto distorcido | regenere esse keyframe, ou remova o produto dos cenários de fala (cartão final + B-roll carregam) |
| Lábios deslizam ou borrão na boca | segmento mais curto (≤ 6 s), keyframe frontal com boca visível, tente o modelo Kling Avatar em config/models.yaml |
| Voz robótica | reduza stability (0,35-0,45), vírgulas para respirações, uma gravação real, ou o modelo eleven-v3 |
| Muito lento / muito longo | finish.tighten_pauses: 0,22, voice.speed: 1,08, corte palavras |
| B-roll parece falso | movimento mais simples (uma ação), with_person: false, ou motion: kenburns em um still bom |
Mais em references/troubleshooting.md.
Arquivos de referência (leia quando necessário)
references/realism-playbook.md: o que faz o UGC de IA parecer real; listas de verificação de keyframe e revisão final do vídeo. Leia antes de planejar cenários e ao revisar imagens.references/script-and-voice.md: estrutura de roteiro UGC para um público indiano com mais de 45 anos, escrevendo para TTS (hindi/hinglish), escolhendo e ajustando vozes, exemplos de roteiros.references/compliance-india.md: consentimento de semelhança, divulgação de IA, regras da Lei DMR / ASCI, uma tabela de redação segura. Leia quandochecksinalizar algo.references/plan-reference.md: todos os campos doplan.yaml.references/models-and-costs.md: qual modelo faz o quê, preços, como trocar por modelos mais novos.references/troubleshooting.md: instalação, chaves, listas de permissão de rede, erros de API, correções.