Fähigkeit zur Capy-Videogenerierung - Skript-zu-Video-Pipeline
Erzeugen Sie komplette Multi-Shot-Videos aus Skripten oder Ideen mit konsistenten Charaktergesichtern in allen Szenen. Entwickelt für den HappyCapy AI Gateway. 300 Experimente validiert, 70% Verbesserung der Gesichtsabstände.
Übersicht
ViMax wandelt Textskripte über eine automatisierte Pipeline in vollständige Videos um:
- Extraktion von Charakteren aus dem Skript mit detaillierten physischen Merkmalen
- Erzeugung von Vorder-/Seiten-/Rücken-Porträts der Charaktere
- Entwurf eines Shot-für-Shot-Storyboards
- Zerlegung jedes Shots in first_frame, last_frame und Bewegungsbeschreibungen
- Aufbau eines Kamerabaums für Shot-Beziehungen
- Frame-Generierung mit Referenzbildauswahl (Gesichtsidentität als oberste Priorität)
- Erzeugung von Videoclips aus den Frames
- Zusammenfügen zum endgültigen Video
Installationsort
Der ViMax-Pipeline-Code befindet sich unter: /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax/
Alle Befehle müssen aus diesem Verzeichnis unter Verwendung der venv ausgeführt werden:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
Voraussetzungen
- Umgebungsvariable
AI_GATEWAY_API_KEY(in HappyCapy automatisch konfiguriert) - Python venv unter
.venv/(bereits eingerichtet)
Schnellstart
Skript-zu-Video
Bearbeiten Sie Skript, Anforderungen und Stil im Einstiegsskript und führen Sie dann aus:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
Idee-zu-Video
Zur Erzeugung aus einer kurzen Idee (erstellt zuerst automatisch ein Skript):
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_idea2video.py
Programmgesteuerte Nutzung
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"],
)
# Pipeline ausführen
asyncio.run(pipeline(
script="Ihr Skript hier...",
user_requirement="Nicht mehr als 8 Shots insgesamt.",
style="Kinoartig, warme Beleuchtung"
))
Pipelines
Script2VideoPipeline
- Eingabe: Ein formatiertes Drehbuch/Skript mit Charakterdialogen und Szenenbeschreibungen
- Ausgabe: Zusammengefügtes Video unter
{working_dir}/final_video.mp4 - Konfiguration:
configs/happycapy_script2video.yaml
Idea2VideoPipeline
- Eingabe: Eine kurze Idee/ein Konzept (1-3 Absätze)
- Ausgabe: Erzeugt automatisch ein Skript und produziert dann das Video
- Konfiguration:
configs/happycapy_idea2video.yaml
Konfiguration
HappyCapy-Konfiguration unter 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
Schlüsselkomponenten
Agents (KI-Verarbeitung)
| Agent | Datei | Zweck |
|---|---|---|
| CharacterExtractor | agents/character_extractor.py | Extrahiert Charaktere mit statischen/dynamischen Merkmalen aus dem Skript |
| CharacterPortraitsGenerator | agents/character_portraits_generator.py | Erzeugt Vorder-/Seiten-/Rücken-Porträts für jeden Charakter |
| StoryboardArtist | agents/storyboard_artist.py | Entwirft Shot-für-Shot-Storyboard mit Erst-/Letztframes und Bewegung |
| ReferenceImageSelector | agents/reference_image_selector.py | Wählt beste Referenzbilder für jeden Frame aus (Gesichtsidentität Priorität #1) |
| CameraImageGenerator | agents/camera_image_generator.py | Baut Kamerabäume und erzeugt Übergangsvideos |
| BestImageSelector | agents/best_image_selector.py | Wählt das beste generierte Bild aus Kandidaten aus |
| Screenwriter | agents/screenwriter.py | Erzeugt Skripte aus Ideen |
Tools (Generierungs-Backends)
| Tool | Datei | Zweck |
|---|---|---|
| ImageGeneratorHappyCapyAPI | tools/image_generator_happycapy_api.py | Bildgenerierung über HappyCapy Gateway (Gemini) |
| VideoGeneratorHappyCapyAPI | tools/video_generator_happycapy_api.py | Videogenerierung über HappyCapy Gateway (Veo) |
| RenderBackend | tools/render_backend.py | Factory zum Instanziieren der Generatoren aus der Konfiguration |
Interfaces (Datenmodelle)
CharacterInScene- Charakter mit Kennung, static_features, dynamic_featuresShotDescription- Shot mit ff_desc, lf_desc, motion_desc, variation_typeCamera- Kamera mit Eltern-Kind-BeziehungenFrame- Frame mit shot_idx, frame_type, sichtbaren CharakterenImageOutput/VideoOutput- Generierungsausgaben mit Speichermethoden
Konsistenz der Gesichtsidentität (KRITISCH)
Diese Pipeline beinhaltet Verbesserungen der Gesichtsidentität, die durch 257 Experimente validiert wurden (70% Verbesserung des Gesichtsabstands, von 0.74 auf 0.22):
Integrierte Schutzmaßnahmen
-
Referenzbildauswahl: Die Gesichtsidentität hat die höchste Priorität bei der Auswahl von Referenzbildern. Die Vorderansicht eines Porträts wird immer dann einbezogen, wenn das Gesicht eines Charakters sichtbar ist.
-
Charakterporträts: Verbesserte Prompts generieren identitätskritische Details (exakte Nasenform, Augenabstand, Kieferlinie, unterscheidende Merkmale) für die szenenübergreifende Erkennung.
-
Videoprompt-Gesichtssperre: Jedem Videogenerierungs-Prompt wird eine Gesichtsidentitätsanweisung vorangestellt, die verlangt, dass das Gesicht des Charakters während des gesamten Clips identisch zum Startframe bleibt.
Best Practices bei der Verwendung von ViMax
- Hyperdetaillierte Charakterbeschreibungen: Fügen Sie ethnische Zugehörigkeit, Alter, Haarstruktur/-stil/-farbe, Augenform, Gesichtsbehaarung, Brille, Hautton, Statur und unterscheidende Merkmale in die Charaktereinführungen Ihres Skripts ein
- Extreme Nahaufnahmen: Fügen Sie mindestens eine extreme Nahaufnahme pro Charakter hinzu, um die Identität zu verankern
- Konsistente Beleuchtung: Geben Sie ähnliche Beleuchtung über Szenen hinweg an, um Gesichtsdrift zu verhindern
- Vom Benutzer bereitgestellte Referenzfotos: Platzieren Sie Fotos im Arbeitsverzeichnis und übergeben Sie sie als
character_portraits_registry, um die KI-Porträtgenerierung zu überspringen
Was NICHT funktioniert
- Komplexes Prompt-Engineering (viseme morphing, phoneme anchoring) verbessert die Gesichtsidentität nicht
- Einfache, direkte Prompts mit detaillierten physischen Beschreibungen sind cleveren Prompts überlegen
- Lippen-Synchronisation mit externem Audio ist NICHT möglich (Veo generiert sein eigenes internes Audio)
Weitere Details finden Sie in FACE_IDENTITY_GUIDE.md im ViMax-Verzeichnis.
Ausgabestruktur
Nach einem Durchlauf enthält das Arbeitsverzeichnis:
.working_dir/script2video/
characters.json # Extrahierte Charaktere
character_portraits_registry.json # Registry der Porträtpfade
character_portraits/ # Generierte Porträts
0_CharacterName/
front.png
side.png
back.png
storyboard.json # Shot-Beschreibungen
camera_tree.json # Kamera-Beziehungen
shots/
0/
shot_description.json
first_frame.png
last_frame.png (bei mittlerer/großer Variation)
video.mp4
1/
...
final_video.mp4 # Endgültige zusammengefügte Ausgabe
Anpassung
Verwendung eigener Referenzfotos
Um echte Fotos anstelle von KI-generierten Porträts zu verwenden:
# Erstellen Sie eine Portrait-Registry, die auf Ihre Fotos verweist
character_portraits_registry = {
"Alice": {
"front": {"path": "/pfad/zu/alice_front.png", "description": "Vorderansicht von Alice"},
"side": {"path": "/pfad/zu/alice_side.png", "description": "Seitenansicht von Alice"},
"back": {"path": "/pfad/zu/alice_back.png", "description": "Rückansicht von Alice"},
}
}
# An Pipeline übergeben (überspringt die Porträtgenerierung)
await pipeline(
script=script,
user_requirement=user_requirement,
style=style,
character_portraits_registry=character_portraits_registry,
)
Ändern der Modelle
Bearbeiten Sie die YAML-Konfiguration, um andere Modelle zu verwenden:
- Bild:
google/gemini-3.1-flash-image-preview(empfohlen für Gesichtsidentität) - Video:
google/veo-3.1-generate-preview(empfohlen) oderopenai/sora-2 - Chat:
gpt-4.1(empfohlen) oder ein beliebiges OpenAI-kompatibles Modell
Fehlerbehebung
"No module named 'tools'" oder ähnliche Importfehler
Führen Sie den Befehl aus dem ViMax-Stammverzeichnis aus:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
API-Ratenlimitfehler
Reduzieren Sie max_requests_per_minute in der YAML-Konfiguration.
Gesichtsidentitätsdrift in generierten Videos
- Fügen Sie mehr physische Details zu den Charakterbeschreibungen in Ihrem Skript hinzu
- Verwenden Sie vom Benutzer bereitgestellte Referenzfotos anstelle von KI-generierten Porträts
- Fügen Sie extreme Nahaufnahmen für wichtige Charaktere ein
- Halten Sie die Beleuchtung über Szenen hinweg konsistent