Habilidad de Generación de Video Capy - Pipeline de Guión a Video
Genera videos completos de múltiples tomas a partir de guiones o ideas, con rostros de personajes consistentes en todas las escenas. Construido para HappyCapy AI Gateway. 300 experimentos validados, mejora del 70% en distancia facial.
Resumen
ViMax convierte guiones de texto en videos completos mediante un pipeline automatizado:
- Extraer personajes del guión con características físicas detalladas
- Generar retratos frontales, laterales y traseros de los personajes
- Diseñar un storyboard toma por toma
- Descomponer cada toma en primer fotograma, último fotograma y descripciones de movimiento
- Construir un árbol de cámaras para las relaciones entre tomas
- Generar fotogramas con selección de imagen de referencia (identidad facial como prioridad máxima)
- Generar clips de video a partir de los fotogramas
- Concatenar en el video final
Ubicación de Instalación
El código del pipeline ViMax está en: /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax/
Todos los comandos deben ejecutarse desde este directorio usando el venv:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
Requisitos Previos
- Variable de entorno
AI_GATEWAY_API_KEY(configurada automáticamente en HappyCapy) - Venv de Python en
.venv/(ya configurado)
Inicio Rápido
De Guión a Video
Edita el guión, los requisitos y el estilo en el script de entrada, luego ejecuta:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
De Idea a Video
Para generar a partir de una idea breve (genera el guión automáticamente primero):
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"],
)
# Ejecutar el pipeline
asyncio.run(pipeline(
script="Tu guión aquí...",
user_requirement="No más de 8 tomas en total.",
style="Cinematográfico, iluminación cálida"
))
Pipelines
Script2VideoPipeline
- Entrada: Un guion formateado con diálogos de personajes y descripciones de escenas
- Salida: Video concatenado en
{working_dir}/final_video.mp4 - Config:
configs/happycapy_script2video.yaml
Idea2VideoPipeline
- Entrada: Una idea/concepto breve (1-3 párrafos)
- Salida: Genera automáticamente un guión y luego produce el video
- Config:
configs/happycapy_idea2video.yaml
Configuración
Configuraciones de HappyCapy en 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 Clave
Agentes (Procesamiento con IA)
| Agente | Archivo | Propósito |
|---|---|---|
| CharacterExtractor | agents/character_extractor.py | Extraer personajes con características estáticas/dinámicas del guión |
| CharacterPortraitsGenerator | agents/character_portraits_generator.py | Generar retratos frontal/lateral/trasero para cada personaje |
| StoryboardArtist | agents/storyboard_artist.py | Diseñar storyboard toma por toma con primer/último fotograma y movimiento |
| ReferenceImageSelector | agents/reference_image_selector.py | Seleccionar las mejores imágenes de referencia para cada fotograma (identidad facial prioridad #1) |
| CameraImageGenerator | agents/camera_image_generator.py | Construir árboles de cámara y generar videos de transición |
| BestImageSelector | agents/best_image_selector.py | Seleccionar la mejor imagen generada entre candidatos |
| Screenwriter | agents/screenwriter.py | Generar guiones a partir de ideas |
Herramientas (Backends de Generación)
| Herramienta | Archivo | Propósito |
|---|---|---|
| ImageGeneratorHappyCapyAPI | tools/image_generator_happycapy_api.py | Generación de imágenes a través de HappyCapy Gateway (Gemini) |
| VideoGeneratorHappyCapyAPI | tools/video_generator_happycapy_api.py | Generación de video a través de HappyCapy Gateway (Veo) |
| RenderBackend | tools/render_backend.py | Fábrica para instanciar generadores desde configuración |
Interfaces (Modelos de Datos)
CharacterInScene- Personaje con identificador, características estáticas y dinámicasShotDescription- Toma con descripción de primer fotograma, último fotograma, movimiento y tipo de variaciónCamera- Cámara con relaciones padre-hijoFrame- Fotograma con índice de toma, tipo de fotograma y personajes visiblesImageOutput/VideoOutput- Salidas de generación con métodos de guardado
Consistencia de Identidad Facial (CRÍTICO)
Este pipeline incluye mejoras de identidad facial validadas a través de 257 experimentos (70% de mejora en distancia facial, de 0.74 a 0.22):
Protecciones Incorporadas
-
Selector de Imagen de Referencia: La identidad facial es la prioridad #1 al seleccionar imágenes de referencia. El retrato frontal siempre se incluye cuando el rostro de un personaje es visible.
-
Retratos de Personajes: Los prompts mejorados generan detalles críticos de identidad (forma exacta de nariz, distancia entre ojos, línea de mandíbula, marcas distintivas) para el reconocimiento entre escenas.
-
Bloqueo Facial en Prompts de Video: Cada prompt de generación de video se antepone con una instrucción de identidad facial que requiere que el rostro del personaje permanezca idéntico al fotograma inicial durante todo el clip.
Mejores Prácticas al Usar ViMax
- Descripciones de personajes hiperdetalladas: Incluye etnia, edad, textura/estilo/color de cabello, forma de ojos, vello facial, gafas, tono de piel, complexión y marcas distintivas en las introducciones de personajes de tu guión
- Tomas de primerísimo primer plano: Incluye al menos un primerísimo primer plano por personaje para anclar la identidad
- Iluminación consistente: Especifica iluminación similar entre escenas para evitar la deriva facial
- Fotos de referencia proporcionadas por el usuario: Coloca fotos en el directorio de trabajo y pásalas como
character_portraits_registrypara omitir la generación de retratos por IA
Lo que NO Funciona
- La ingeniería de prompts compleja (morfología de visemas, anclaje de fonemas) no mejora la identidad facial
- Los prompts simples y directos con descripciones físicas detalladas superan a los prompts ingeniosos
- La sincronización de labios con audio externo NO es posible (Veo genera su propio audio interno)
Consulta FACE_IDENTITY_GUIDE.md en el directorio ViMax para todos los detalles.
Estructura de Salida
Después de una ejecución, el directorio de trabajo contiene:
.working_dir/script2video/
characters.json # Personajes extraídos
character_portraits_registry.json # Registro de rutas de retratos
character_portraits/ # Retratos generados
0_CharacterName/
front.png
side.png
back.png
storyboard.json # Descripciones de tomas
camera_tree.json # Relaciones de cámara
shots/
0/
shot_description.json
first_frame.png
last_frame.png (si variación media/grande)
video.mp4
1/
...
final_video.mp4 # Salida final concatenada
Personalización
Usar tus Propias Fotos de Referencia
Para usar fotos reales en lugar de retratos generados por IA:
# Construir un registro de retratos que apunte a tus fotos
character_portraits_registry = {
"Alice": {
"front": {"path": "/ruta/a/alice_front.png", "description": "Vista frontal de Alice"},
"side": {"path": "/ruta/a/alice_side.png", "description": "Vista lateral de Alice"},
"back": {"path": "/ruta/a/alice_back.png", "description": "Vista trasera de Alice"},
}
}
# Pasar al pipeline (omite la generación de retratos)
await pipeline(
script=script,
user_requirement=user_requirement,
style=style,
character_portraits_registry=character_portraits_registry,
)
Cambiar Modelos
Edita la configuración YAML para usar diferentes modelos:
- Imagen:
google/gemini-3.1-flash-image-preview(recomendado para identidad facial) - Video:
google/veo-3.1-generate-preview(recomendado) oopenai/sora-2 - Chat:
gpt-4.1(recomendado) o cualquier modelo compatible con OpenAI
Solución de Problemas
"No module named 'tools'" o errores de importación similares
Ejecuta desde el directorio raíz de ViMax:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
Errores de límite de velocidad de API
Reduce max_requests_per_minute en la configuración YAML.
Deriva de identidad facial en videos generados
- Añade más detalles físicos a las descripciones de personajes en tu guión
- Usa fotos de referencia proporcionadas por el usuario en lugar de retratos generados por IA
- Incluye tomas de primerísimo primer plano para personajes importantes
- Mantén la iluminación consistente entre escenas