Capy 비디오 생성 스킬 - 스크립트-투-비디오 파이프라인
스크립트나 아이디어에서 모든 장면에 걸쳐 일관된 캐릭터 얼굴을 가진 완전한 멀티 샷 비디오를 생성합니다. HappyCapy AI 게이트웨이용으로 제작되었습니다. 300회 실험 검증, 70% 얼굴 거리 개선.
개요
ViMax는 텍스트 스크립트를 자동화된 파이프라인을 통해 전체 비디오로 변환합니다:
- 상세한 신체적 특징과 함께 스크립트에서 캐릭터 추출
- 캐릭터의 전면/측면/후면 초상화 생성
- 샷별 스토리보드 설계
- 각 샷을 첫 번째 프레임, 마지막 프레임, 모션 설명으로 분해
- 샷 관계를 위한 카메라 트리 구축
- 참조 이미지 선택으로 프레임 생성 (얼굴 정체성 최우선)
- 프레임에서 비디오 클립 생성
- 최종 비디오로 연결
설치 위치
ViMax 파이프라인 코드 위치: /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax/
모든 명령은 이 디렉토리에서 venv를 사용하여 실행해야 합니다:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
사전 요구 사항
AI_GATEWAY_API_KEY환경 변수 (HappyCapy에서 자동 구성).venv/의 Python 가상 환경 (이미 설정됨)
빠른 시작
스크립트-투-비디오
진입 스크립트에서 스크립트, 요구 사항 및 스타일을 편집한 후 실행:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
아이디어-투-비디오
간단한 아이디어로 생성 (먼저 스크립트 자동 생성):
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_idea2video.py
프로그래매틱 사용법
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"],
)
# 파이프라인 실행
asyncio.run(pipeline(
script="여기에 스크립트 입력...",
user_requirement="최대 8샷.",
style="시네마틱, 따뜻한 조명"
))
파이프라인
Script2VideoPipeline
- 입력: 캐릭터 대화와 장면 설명이 포함된 형식화된 시나리오/스크립트
- 출력:
{working_dir}/final_video.mp4에 연결된 비디오 - 설정:
configs/happycapy_script2video.yaml
Idea2VideoPipeline
- 입력: 간단한 아이디어/개념 (1-3 문단)
- 출력: 스크립트를 자동 생성한 후 비디오 생성
- 설정:
configs/happycapy_idea2video.yaml
설정
configs/happycapy_script2video.yaml의 HappyCapy 설정:
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
주요 구성 요소
에이전트 (AI 처리)
| 에이전트 | 파일 | 목적 |
|---|---|---|
| CharacterExtractor | agents/character_extractor.py | 스크립트에서 정적/동적 특징을 가진 캐릭터 추출 |
| CharacterPortraitsGenerator | agents/character_portraits_generator.py | 각 캐릭터의 전면/측면/후면 초상화 생성 |
| StoryboardArtist | agents/storyboard_artist.py | 첫/마지막 프레임과 모션이 포함된 샷별 스토리보드 설계 |
| ReferenceImageSelector | agents/reference_image_selector.py | 각 프레임에 가장 적합한 참조 이미지 선택 (얼굴 정체성 #1 우선순위) |
| CameraImageGenerator | agents/camera_image_generator.py | 카메라 트리 구축 및 전환 비디오 생성 |
| BestImageSelector | agents/best_image_selector.py | 후보 이미지 중 최고 이미지 선택 |
| Screenwriter | agents/screenwriter.py | 아이디어에서 스크립트 생성 |
도구 (생성 백엔드)
| 도구 | 파일 | 목적 |
|---|---|---|
| ImageGeneratorHappyCapyAPI | tools/image_generator_happycapy_api.py | HappyCapy 게이트웨이를 통한 이미지 생성 (Gemini) |
| VideoGeneratorHappyCapyAPI | tools/video_generator_happycapy_api.py | HappyCapy 게이트웨이를 통한 비디오 생성 (Veo) |
| RenderBackend | tools/render_backend.py | 설정에서 생성기 인스턴스화를 위한 팩토리 |
인터페이스 (데이터 모델)
CharacterInScene- 식별자, static_features, dynamic_features를 가진 캐릭터ShotDescription- ff_desc, lf_desc, motion_desc, variation_type을 가진 샷Camera- 부모-자식 관계를 가진 카메라Frame- shot_idx, frame_type, visible characters를 가진 프레임ImageOutput/VideoOutput- 저장 메서드가 있는 생성 출력
얼굴 정체성 일관성 (중요)
이 파이프라인은 257회 실험을 통해 검증된 얼굴 정체성 개선 기능을 포함합니다 (70% 얼굴 거리 개선, 0.74에서 0.22로):
내장 보호 기능
-
참조 이미지 선택기: 참조 이미지 선택 시 얼굴 정체성이 #1 우선순위입니다. 캐릭터의 얼굴이 보일 때 전면 초상화가 항상 포함됩니다.
-
캐릭터 초상화: 향상된 프롬프트가 정체성에 중요한 세부 정보(정확한 코 모양, 눈 간격, 턱선, 식별 표시)를 생성하여 장면 간 인식을 지원합니다.
-
비디오 프롬프트 얼굴 잠금: 모든 비디오 생성 프롬프트 앞에 클립 전체에서 캐릭터의 얼굴이 시작 프레임과 동일하게 유지되도록 하는 얼굴 정체성 지시가 추가됩니다.
ViMax 사용 시 모범 사례
- 초세부 캐릭터 설명: 스크립트의 캐릭터 소개에 민족, 나이, 헤어 텍스처/스타일/색상, 눈 모양, 수염, 안경, 피부톤, 체형, 식별 표시 포함
- 극단적 클로즈업 샷: 캐릭터당 최소 하나의 극단적 클로즈업 샷을 포함하여 정체성 고정
- 일관된 조명: 장면 간 유사한 조명을 지정하여 얼굴 드리프트 방지
- 사용자 제공 참조 사진: 작업 디렉토리에 사진을 배치하고
character_portraits_registry로 전달하여 AI 초상화 생성 건너뛰기
작동하지 않는 것
- 복잡한 프롬프트 엔지니어링(viseme 모핑, phoneme 앵커링)은 얼굴 정체성을 개선하지 않음
- 상세한 신체적 설명이 포함된 단순하고 직접적인 프롬프트가 복잡한 프롬프트보다 성능 우수
- 외부 오디오에 대한 립싱크는 불가능 (Veo가 자체 내부 오디오 생성)
자세한 내용은 ViMax 디렉토리의 FACE_IDENTITY_GUIDE.md 참조.
출력 구조
실행 후 작업 디렉토리에는 다음이 포함됩니다:
.working_dir/script2video/
characters.json # 추출된 캐릭터
character_portraits_registry.json # 초상화 경로 레지스트리
character_portraits/ # 생성된 초상화
0_CharacterName/
front.png
side.png
back.png
storyboard.json # 샷 설명
camera_tree.json # 카메라 관계
shots/
0/
shot_description.json
first_frame.png
last_frame.png (중간/큰 변동인 경우)
video.mp4
1/
...
final_video.mp4 # 최종 연결된 출력
사용자 정의
나만의 참조 사진 사용하기
AI 생성 초상화 대신 실제 사진을 사용하려면:
# 사진을 가리키는 초상화 레지스트리 구축
character_portraits_registry = {
"Alice": {
"front": {"path": "/path/to/alice_front.png", "description": "Alice의 전면"},
"side": {"path": "/path/to/alice_side.png", "description": "Alice의 측면"},
"back": {"path": "/path/to/alice_back.png", "description": "Alice의 후면"},
}
}
# 파이프라인에 전달 (초상화 생성 건너뜀)
await pipeline(
script=script,
user_requirement=user_requirement,
style=style,
character_portraits_registry=character_portraits_registry,
)
모델 변경
YAML 설정을 편집하여 다른 모델 사용:
- 이미지:
google/gemini-3.1-flash-image-preview(얼굴 정체성에 권장) - 비디오:
google/veo-3.1-generate-preview(권장) 또는openai/sora-2 - 채팅:
gpt-4.1(권장) 또는 모든 OpenAI 호환 모델
문제 해결
"No module named 'tools'" 또는 유사한 가져오기 오류
ViMax 루트 디렉토리에서 실행:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
API 속도 제한 오류
YAML 설정에서 max_requests_per_minute를 줄이세요.
생성된 비디오의 얼굴 정체성 드리프트
- 스크립트의 캐릭터 설명에 더 많은 신체적 세부 정보 추가
- AI 생성 초상화 대신 사용자 제공 참조 사진 사용
- 중요한 캐릭터에 극단적 클로즈업 샷 포함
- 장면 간 조명 일관성 유지