Habilidade de Geração de Vídeo Capy - Pipeline Script-para-Vídeo
Gere vídeos completos com múltiplos planos a partir de roteiros ou ideias, mantendo rostos consistentes em todas as cenas. Construído para o HappyCapy AI Gateway. 300 experimentos validados, melhoria de 70% na distância facial.
Visão Geral
O ViMax converte roteiros de texto em vídeos completos por meio de um pipeline automatizado:
- Extrair personagens do roteiro com características físicas detalhadas
- Gerar retratos frontal/lateral/costas dos personagens
- Projetar storyboard plano a plano
- Decompor cada plano em first_frame, last_frame e descrições de movimento
- Construir árvore de câmeras para relações entre planos
- Gerar quadros com seleção de imagem de referência (identidade facial como prioridade máxima)
- Gerar clipes de vídeo a partir dos quadros
- Concatenar em um vídeo final
Localização da Instalação
O código do pipeline ViMax está em: /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax/
Todos os comandos devem ser executados a partir deste diretório usando o venv:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
Pré-requisitos
- Variável de ambiente
AI_GATEWAY_API_KEY(configurada automaticamente no HappyCapy) - Venv Python em
.venv/(já configurado)
Início Rápido
Script-para-Vídeo
Edite o script, os requisitos e o estilo no script de entrada e execute:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
Ideia-para-Vídeo
Para gerar a partir de uma ideia breve (gera o script automaticamente primeiro):
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_idea2video.py
Uso Programático
import asyncio
from langchain.chat_models import init_chat_model
from tools.render_backend import RenderBackend
from utils.config_loader import load_config
from pipelines.script2video_pipeline import Script2VideoPipeline
config = load_config("configs/happycapy_script2video.yaml")
chat_model = init_chat_model(**config["chat_model"]["init_args"])
backend = RenderBackend.from_config(config)
pipeline = Script2VideoPipeline(
chat_model=chat_model,
image_generator=backend.image_generator,
video_generator=backend.video_generator,
working_dir=config["working_dir"],
)
# Executa o pipeline
asyncio.run(pipeline(
script="Seu roteiro aqui...",
user_requirement="No máximo 8 planos no total.",
style="Cinematográfico, iluminação quente"
))
Pipelines
Script2VideoPipeline
- Entrada: Um roteiro formatado com diálogos e descrições de cena
- Saída: Vídeo concatenado em
{working_dir}/final_video.mp4 - Config:
configs/happycapy_script2video.yaml
Idea2VideoPipeline
- Entrada: Uma ideia/conceito breve (1-3 parágrafos)
- Saída: Gera automaticamente um roteiro e depois produz o vídeo
- Config:
configs/happycapy_idea2video.yaml
Configuração
Configurações do HappyCapy em configs/happycapy_script2video.yaml:
chat_model:
init_args:
model: gpt-4.1
model_provider: openai
api_key: ${AI_GATEWAY_API_KEY}
base_url: https://ai-gateway.happycapy.ai/api/v1/openai/v1
image_generator:
class_path: tools.ImageGeneratorHappyCapyAPI
init_args:
api_key: ${AI_GATEWAY_API_KEY}
model: google/gemini-3.1-flash-image-preview
video_generator:
class_path: tools.VideoGeneratorHappyCapyAPI
init_args:
api_key: ${AI_GATEWAY_API_KEY}
model: google/veo-3.1-generate-preview
working_dir: .working_dir/script2video
Componentes Principais
Agentes (Processamento de IA)
| Agente | Arquivo | Propósito |
|---|---|---|
| CharacterExtractor | agents/character_extractor.py | Extrair personagens com características estáticas/dinâmicas do roteiro |
| CharacterPortraitsGenerator | agents/character_portraits_generator.py | Gerar retratos frontal/lateral/costas para cada personagem |
| StoryboardArtist | agents/storyboard_artist.py | Projetar storyboard plano a plano com first/last frames e movimento |
| ReferenceImageSelector | agents/reference_image_selector.py | Selecionar as melhores imagens de referência para cada quadro (identidade facial #1 prioridade) |
| CameraImageGenerator | agents/camera_image_generator.py | Criar árvores de câmera e gerar vídeos de transição |
| BestImageSelector | agents/best_image_selector.py | Selecionar a melhor imagem gerada entre candidatas |
| Screenwriter | agents/screenwriter.py | Gerar roteiros a partir de ideias |
Ferramentas (Backends de Geração)
| Ferramenta | Arquivo | Propósito |
|---|---|---|
| ImageGeneratorHappyCapyAPI | tools/image_generator_happycapy_api.py | Geração de imagens via HappyCapy Gateway (Gemini) |
| VideoGeneratorHappyCapyAPI | tools/video_generator_happycapy_api.py | Geração de vídeo via HappyCapy Gateway (Veo) |
| RenderBackend | tools/render_backend.py | Fábrica para instanciar geradores a partir da configuração |
Interfaces (Modelos de Dados)
CharacterInScene- Personagem com identificador, static_features, dynamic_featuresShotDescription- Plano com ff_desc, lf_desc, motion_desc, variation_typeCamera- Câmera com relacionamentos pai-filhoFrame- Quadro com shot_idx, frame_type, personagens visíveisImageOutput/VideoOutput- Saídas de geração com métodos de salvamento
Consistência de Identidade Facial (CRÍTICO)
Este pipeline inclui melhorias de identidade facial validadas em 257 experimentos (melhoria de 70% na distância facial, de 0.74 para 0.22):
Proteções Integradas
-
Seletor de Imagem de Referência: Identidade facial é a prioridade #1 ao selecionar imagens de referência. O retrato frontal é sempre incluído quando o rosto de um personagem está visível.
-
Retratos de Personagens: Prompts aprimorados geram detalhes críticos de identidade (formato exato do nariz, espaçamento dos olhos, linha do maxilar, marcas distintivas) para reconhecimento entre cenas.
-
Travamento Facial no Prompt de Vídeo: Todo prompt de geração de vídeo é precedido por uma instrução de identidade facial exigindo que o rosto do personagem permaneça idêntico ao quadro inicial durante todo o clipe.
Melhores Práticas ao Usar o ViMax
- Descrições de personagens hiperdetalhadas: Inclua etnia, idade, textura/estilo/cor do cabelo, formato dos olhos, pelos faciais, óculos, tom de pele, biotipo e marcas distintivas nas introduções de personagem do seu roteiro
- Planos com close-up extremo: Inclua pelo menos um close-up extremo por personagem para ancorar a identidade
- Iluminação consistente: Especifique iluminação semelhante em todas as cenas para evitar desvio facial
- Fotos de referência fornecidas pelo usuário: Coloque fotos no diretório de trabalho e passe-as como
character_portraits_registrypara pular a geração de retratos por IA
O que NÃO Funciona
- Engenharia de prompt complexa (morfagem de visemas, ancoragem de fonemas) não melhora a identidade facial
- Prompts simples e diretos com descrições físicas detalhadas superam prompts engenhosos
- Sincronização labial com áudio externo NÃO é possível (Veo gera seu próprio áudio interno)
Consulte FACE_IDENTITY_GUIDE.md no diretório ViMax para detalhes completos.
Estrutura de Saída
Após uma execução, o diretório de trabalho contém:
.working_dir/script2video/
characters.json # Personagens extraídos
character_portraits_registry.json # Registro de caminhos de retratos
character_portraits/ # Retratos gerados
0_NomeDoPersonagem/
front.png
side.png
back.png
storyboard.json # Descrições dos planos
camera_tree.json # Relacionamentos de câmera
shots/
0/
shot_description.json
first_frame.png
last_frame.png (se variação média/grande)
video.mp4
1/
...
final_video.mp4 # Saída final concatenada
Personalização
Usando Suas Próprias Fotos de Referência
Para usar fotos reais em vez de retratos gerados por IA:
# Construa um registro de retratos apontando para suas fotos
character_portraits_registry = {
"Alice": {
"front": {"path": "/caminho/para/alice_front.png", "description": "Vista frontal da Alice"},
"side": {"path": "/caminho/para/alice_side.png", "description": "Vista lateral da Alice"},
"back": {"path": "/caminho/para/alice_back.png", "description": "Vista traseira da Alice"},
}
}
# Passe para o pipeline (pula a geração de retratos)
await pipeline(
script=script,
user_requirement=user_requirement,
style=style,
character_portraits_registry=character_portraits_registry,
)
Alterando Modelos
Edite a configuração YAML para usar modelos diferentes:
- Imagem:
google/gemini-3.1-flash-image-preview(recomendado para identidade facial) - Vídeo:
google/veo-3.1-generate-preview(recomendado) ouopenai/sora-2 - Chat:
gpt-4.1(recomendado) ou qualquer modelo compatível com OpenAI
Solução de Problemas
"No module named 'tools'" ou erros de importação semelhantes
Execute a partir do diretório raiz do ViMax:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
Erros de limite de taxa da API
Reduza max_requests_per_minute na configuração YAML.
Desvio de identidade facial nos vídeos gerados
- Adicione mais detalhes físicos às descrições de personagens no seu roteiro
- Use fotos de referência fornecidas pelo usuário em vez de retratos gerados por IA
- Inclua planos com close-up extremo para personagens importantes
- Mantenha a iluminação consistente em todas as cenas