Compétence de Génération Vidéo Capy - Pipeline Script vers Vidéo
Générez des vidéos multi-plans complètes à partir de scripts ou d'idées, avec des visages de personnages cohérents dans toutes les scènes. Conçu pour HappyCapy AI Gateway. 300 expériences validées, amélioration de 70% de la distance faciale.
Aperçu
ViMax transforme des scripts textuels en vidéos complètes via un pipeline automatisé :
- Extraire les personnages du script avec des caractéristiques physiques détaillées
- Générer des portraits de face/profil/dos des personnages
- Concevoir un storyboard plan par plan
- Décomposer chaque plan en descriptions de première_image, dernière_image et mouvement
- Construire un arbre de caméras pour les relations entre plans
- Générer les images avec sélection d'images de référence (identité faciale comme priorité absolue)
- Générer des clips vidéo à partir des images
- Concaténer en une vidéo finale
Emplacement d'Installation
Le code du pipeline ViMax se trouve à : /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax/
Toutes les commandes doivent être exécutées depuis ce répertoire en utilisant le venv :
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
Prérequis
- Variable d'environnement
AI_GATEWAY_API_KEY(préconfigurée dans HappyCapy) - Venv Python à
.venv/(déjà configuré)
Démarrage Rapide
Script vers Vidéo
Modifiez le script, les exigences et le style dans le script d'entrée, puis exécutez :
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
Idée vers Vidéo
Pour générer à partir d'une brève idée (génère d'abord le script automatiquement) :
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_idea2video.py
Utilisation Programmatique
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"],
)
# Exécuter le pipeline
asyncio.run(pipeline(
script="Votre script ici...",
user_requirement="Pas plus de 8 plans au total.",
style="Cinématographique, éclairage chaleureux"
))
Pipelines
Script2VideoPipeline
- Entrée : Un scénario/script formaté avec dialogues de personnages et descriptions de scènes
- Sortie : Vidéo concaténée à
{working_dir}/final_video.mp4 - Configuration :
configs/happycapy_script2video.yaml
Idea2VideoPipeline
- Entrée : Une brève idée/concept (1 à 3 paragraphes)
- Sortie : Génère automatiquement un script, puis produit la vidéo
- Configuration :
configs/happycapy_idea2video.yaml
Configuration
Configurations HappyCapy dans 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
Composants Clés
Agents (Traitement IA)
| Agent | Fichier | Objectif |
|---|---|---|
| CharacterExtractor | agents/character_extractor.py | Extraire les personnages avec caractéristiques statiques/dynamiques du script |
| CharacterPortraitsGenerator | agents/character_portraits_generator.py | Générer des portraits de face/profil/dos pour chaque personnage |
| StoryboardArtist | agents/storyboard_artist.py | Concevoir un storyboard plan par plan avec première/dernière image et mouvement |
| ReferenceImageSelector | agents/reference_image_selector.py | Sélectionner les meilleures images de référence pour chaque image (priorité #1 à l'identité faciale) |
| CameraImageGenerator | agents/camera_image_generator.py | Construire des arbres de caméras et générer des vidéos de transition |
| BestImageSelector | agents/best_image_selector.py | Sélectionner la meilleure image générée parmi les candidates |
| Screenwriter | agents/screenwriter.py | Générer des scripts à partir d'idées |
Outils (Moteurs de Génération)
| Outil | Fichier | Objectif |
|---|---|---|
| ImageGeneratorHappyCapyAPI | tools/image_generator_happycapy_api.py | Génération d'images via HappyCapy Gateway (Gemini) |
| VideoGeneratorHappyCapyAPI | tools/video_generator_happycapy_api.py | Génération vidéo via HappyCapy Gateway (Veo) |
| RenderBackend | tools/render_backend.py | Fabrique pour instancier les générateurs à partir de la configuration |
Interfaces (Modèles de Données)
CharacterInScene- Personnage avec identifiant, static_features, dynamic_featuresShotDescription- Plan avec ff_desc, lf_desc, motion_desc, variation_typeCamera- Caméra avec relations parent-enfantFrame- Image avec shot_idx, frame_type, personnages visiblesImageOutput/VideoOutput- Sorties de génération avec méthodes de sauvegarde
Cohérence de l'Identité Faciale (CRITIQUE)
Ce pipeline inclut des améliorations de l'identité faciale validées par 257 expériences (amélioration de 70% de la distance faciale, passant de 0,74 à 0,22) :
Protections Intégrées
-
Sélecteur d'Image de Référence : L'identité faciale est la priorité #1 lors de la sélection des images de référence. Le portrait de face est toujours inclus lorsque le visage d'un personnage est visible.
-
Portraits de Personnages : Des prompts enrichis génèrent des détails critiques pour l'identité (forme exacte du nez, écartement des yeux, mâchoire, signes distinctifs) pour une reconnaissance inter-scènes.
-
Verrou Facial dans le Prompt Vidéo : Chaque prompt de génération vidéo est précédé d'une instruction d'identité faciale exigeant que le visage du personnage reste identique à l'image de départ tout au long du clip.
Meilleures Pratiques avec ViMax
- Descriptions hyper-détaillées des personnages : Incluez l'ethnie, l'âge, la texture/style/couleur des cheveux, la forme des yeux, la pilosité faciale, les lunettes, le teint, la corpulence et les signes distinctifs dans les présentations des personnages de votre script
- Plans en très gros plan : Incluez au moins un très gros plan par personnage pour ancrer son identité
- Éclairage cohérent : Spécifiez un éclairage similaire entre les scènes pour éviter la dérive faciale
- Photos de référence fournies par l'utilisateur : Placez les photos dans le répertoire de travail et passez-les en tant que
character_portraits_registrypour ignorer la génération de portraits IA
Ce Qui NE Fonctionne PAS
- L'ingénierie de prompts complexe (morphing visème, ancrage phonème) n'améliore pas l'identité faciale
- Les prompts simples et directs avec des descriptions physiques détaillées surpassent les prompts astucieux
- Le synchronisme labial avec un audio externe n'est PAS possible (Veo génère son propre audio interne)
Voir FACE_IDENTITY_GUIDE.md dans le répertoire ViMax pour tous les détails.
Structure de Sortie
Après une exécution, le répertoire de travail contient :
.working_dir/script2video/
characters.json # Personnages extraits
character_portraits_registry.json # Registre des chemins des portraits
character_portraits/ # Portraits générés
0_CharacterName/
front.png
side.png
back.png
storyboard.json # Descriptions des plans
camera_tree.json # Relations des caméras
shots/
0/
shot_description.json
first_frame.png
last_frame.png (si variation moyenne/importante)
video.mp4
1/
...
final_video.mp4 # Sortie finale concaténée
Personnalisation
Utiliser Vos Propres Photos de Référence
Pour utiliser de vraies photos au lieu de portraits générés par IA :
# Construire un registre de portraits pointant vers vos photos
character_portraits_registry = {
"Alice": {
"front": {"path": "/chemin/vers/alice_front.png", "description": "Vue de face d'Alice"},
"side": {"path": "/chemin/vers/alice_side.png", "description": "Vue de profil d'Alice"},
"back": {"path": "/chemin/vers/alice_back.png", "description": "Vue de dos d'Alice"},
}
}
# Passer au pipeline (ignore la génération de portraits)
await pipeline(
script=script,
user_requirement=user_requirement,
style=style,
character_portraits_registry=character_portraits_registry,
)
Changer les Modèles
Modifiez la configuration YAML pour utiliser différents modèles :
- Image :
google/gemini-3.1-flash-image-preview(recommandé pour l'identité faciale) - Vidéo :
google/veo-3.1-generate-preview(recommandé) ouopenai/sora-2 - Chat :
gpt-4.1(recommandé) ou tout modèle compatible OpenAI
Dépannage
"No module named 'tools'" ou erreurs d'import similaires
Exécutez depuis le répertoire racine ViMax :
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
Erreurs de limite de débit API
Réduisez max_requests_per_minute dans la configuration YAML.
Dérive de l'identité faciale dans les vidéos générées
- Ajoutez plus de détails physiques aux descriptions des personnages dans votre script
- Utilisez des photos de référence fournies par l'utilisateur au lieu de portraits générés par IA
- Incluez des plans en très gros plan pour les personnages importants
- Maintenez un éclairage cohérent entre les scènes