ViMax — 아이디어·대본·소설을 멀티샷 영상으로 확장하는 Agentic Video Generation 프레임워크

ViMax는 짧은 클립 생성에 머무르는 일반적인 비디오 생성 워크플로를 넘어, 아이디어·스크립트·소설을 입력으로 받아 대본 작성, 캐릭터 추출, 스토리보드 설계, 참조 이미지 선택, 프레임 생성, 비디오 생성, 클립 조립까지 자동화하려는 멀티 에이전트 영상 제작 프레임워크다. 핵심 가치는 “한 번의 내러티브 입력을 장면 단위의 일관된 영상 파이프라인으로 분해하고 다시 조립하는 것”이다.

그림 1. 저장소에서 수집한 ViMax 공식 배너. 이 이미지는 프로젝트의 정체성과 “Agentic Video Generation” 방향성을 소개하는 데 사용했다.

Quick Links

구분	링크
GitHub Repository	HKUDS/ViMax
README	readme.md
Technical Report	assets/ViMax_technical_report.pdf
README Demo Video	GitHub user-attachment demo
Main Entrypoints	main_idea2video.py, main_script2video.py
Core Pipelines	pipelines/idea2video_pipeline.py, pipelines/script2video_pipeline.py
Model Configs	configs/idea2video.yaml, configs/script2video.yaml

참고: 공개 GitHub 경로에서 Wiki와 Discussion 탭은 확인되지 않았기 때문에,
이 리포트는 README, 이슈 목록, 소스 구조, 설정 파일, 파이프라인 구현을 중심으로 작성했다.

Key Features

1. Idea2Video: 한 줄 아이디어를 장면 기반 영상 시나리오로 확장

Idea2VideoPipeline은 사용자의 아이디어, 요구사항, 스타일을 받아 Screenwriter로 스토리를 발전시키고, 장면별로 Script2VideoPipeline을 호출해 최종 클립을 조립한다. 단순 프롬프트를 곧바로 비디오 모델에 보내는 방식이 아니라, 이야기 → 대본 → 장면 → 샷 → 프레임 → 비디오로 내려가는 제작 흐름을 만든다는 점이 중요하다.

2. Script2Video: 대본을 샷 단위 시각 계획으로 변환

스크립트 기반 실행은 캐릭터 추출, 초상 이미지 생성, 스토리보드 설계, 카메라 트리 구성, 참조 이미지 선택, 프레임 생성, 샷 비디오 생성, 최종 연결로 이어진다. 이 구조는 “대본을 비디오로 만든다”는 추상적 목표를 실제 운영 가능한 DAG에 가깝게 분해한다.

그림 2. script2video_pipeline.py의 실행 흐름을 기반으로 재구성한 처리 파이프라인. 스크립트가 캐릭터 라이브러리, 스토리보드, 카메라 트리, 참조 프레임, 샷 클립으로 단계적으로 변환된다.

3. Novel2Video: 긴 내러티브를 장면 단위로 압축·분절

README는 Novel2Video를 “complete novels into episodic video content”로 설명한다. 저장소에는 novel2movie_pipeline.py, novel_compressor.py, scene_extractor.py, event_extractor.py가 포함되어 있어, 긴 원문을 그대로 영상 모델에 전달하지 않고 장면·이벤트·캐릭터 중심의 중간 표현으로 바꾸려는 설계를 확인할 수 있다. 장문 내러티브를 영상화할 때 핵심 병목인 분량 압축, 장면 경계, 캐릭터 추적을 별도 모듈로 다루는 접근이다.

4. 참조 이미지 기반 일관성 제어

ViMax의 강점은 캐릭터나 배경이 장면마다 흔들리는 문제를 “참조 이미지 선택”과 “프레임 후보 검증”으로 줄이려는 점이다. ReferenceImageSelector는 캐릭터 초상, 이전 타임라인 프레임, 환경·스타일 이미지를 기준으로 현재 샷에 필요한 참조 이미지를 고르고, 이미지 생성 단계는 해당 참조와 프롬프트를 조합한다. 이후 BestImageSelector가 병렬 생성된 후보 중 가장 일관된 프레임을 선택하도록 설계되어 있다.

그림 3. ViMax의 참조 이미지 재사용 구조. 이전 장면의 프레임과 캐릭터 초상을 현재 샷 생성에 다시 주입해 장편 영상에서 외형·배경·구도 일관성을 유지하려는 기능을 설명한다.

5. 멀티카메라 촬영 시뮬레이션과 병렬 샷 생성

README는 “Multi-camera Filming Simulation”과 “High-efficiency Parallel Shot Generation”을 강조한다. 코드상으로도 샷은 카메라 구조에 따라 그룹화되고, 동일 카메라 시퀀스에 속한 작업은 비동기 태스크로 처리된다. 이 방식은 장면 내 시점 전환, 컷 구성, 반복되는 캐릭터 위치 관계를 유지하는 데 유리하다.

6. RenderBackend: 공급자 교체형 이미지·비디오 생성 어댑터

tools/render_backend.py는 YAML 설정의 class_path를 읽어 이미지 생성기와 비디오 생성기를 동적으로 인스턴스화한다. 기본 예시는 Google Gemini 계열 이미지 생성기와 Veo 비디오 생성기를 사용하지만, MiniMax 프리셋과 OpenAI 호환 API 흐름도 제공한다. 덕분에 파이프라인 자체는 특정 모델에 완전히 묶이지 않고, “제작 로직”과 “모델 공급자”를 분리한다.

7. 작업 디렉터리 중심의 산출물 추적

working_dir에는 캐릭터 이미지, 첫 프레임·마지막 프레임, 샷 클립, 장면 클립, 로그성 중간 산출물이 쌓인다. 이는 블로그·연구·제품 관점 모두에서 중요하다. 생성형 비디오 파이프라인은 비용과 실패율이 높기 때문에, 중간 산출물 재사용과 실패 단계 재실행이 곧 생산성으로 이어진다.

Tech Stack

영역	기술
언어·런타임	Python >=3.12
패키지 관리	uv
LLM orchestration	LangChain, LangChain OpenAI, Pydantic 기반 출력 파싱
이미지 생성	google-genai, Gemini/NanoBanana 계열 adapter, 참조 이미지 입력 지원
비디오 생성	Google Veo adapter, 텍스트·첫 프레임·첫/마지막 프레임 기반 생성 지원
비디오 조립	MoviePy >=2.2.1
영상·장면 유틸	OpenCV, PySceneDetect
검색·재랭킹	FAISS CPU, BGE reranker 관련 도구
API 호환	OpenRouter, OpenAI 호환 provider, MiniMax preset
동시성·안정화	asyncio, rate limiter, retry utility
설정	YAML 기반 chat_model, image_generator, video_generator, working_dir 구성

Architecture

그림 4. README와 핵심 파이프라인 소스 코드를 기반으로 재구성한 ViMax 시스템 아키텍처. 공식 저장소의 설명과 코드 흐름을 시각화한 분석 다이어그램이다.

 

ViMax는 크게 여섯 계층으로 읽을 수 있다.

1. Input Layer: 아이디어, 스크립트, 소설, 자연어 요구사항, 스타일 지시, 참조 이미지, YAML 설정을 입력으로 받는다.
2. Central Orchestration: Idea2VideoPipeline, Script2VideoPipeline, Novel2MoviePipeline이 장면 전환, 에이전트 호출, 리소스 관리, 최종 조립을 담당한다.
3. Script Understanding: 캐릭터, 환경, 이벤트, 장면 경계, 스타일 의도를 구조화한다.
4. Scene & Shot Planning: StoryboardArtist가 샷 목록, 장면 비트, 첫/마지막 프레임 의도, 카메라 표현을 만든다.
5. Visual Asset Planning & Continuity: ReferenceImageSelector와 관련 유틸이 캐릭터 초상, 이전 프레임, 환경 참조를 선택한다.
6. Visual Synthesis & Assembly: 이미지 생성기로 키프레임을 만들고, 비디오 생성기로 샷 클립을 만든 뒤, MoviePy로 장면과 최종 영상을 연결한다.

코드 구조 관점

ViMax/
├── agents/       # Screenwriter, StoryboardArtist, ReferenceImageSelector 등 역할별 에이전트
├── configs/      # idea2video/script2video YAML 설정, MiniMax 설정 예시
├── interfaces/   # Character, Scene, Camera, Frame, VideoOutput 등 중간 데이터 구조
├── pipelines/    # idea2video, script2video, novel2movie 실행 흐름
├── tools/        # image/video generator, render backend, reranker, provider adapter
├── utils/        # rate limiter, retry, image/video utility, provider presets
├── main_idea2video.py
└── main_script2video.py

 

이 구조는 에이전트형 생성 시스템의 전형적인 장점을 가진다. 역할별 에이전트가 명확히 분리되어 있어 실패 지점을 추적하기 쉽고, 이미지·비디오 모델 공급자는 RenderBackend 뒤로 숨겨져 있으며, 중간 산출물은 working_dir에 보존된다. 반대로 전체 품질은 각 단계의 프롬프트 안정성, 모델 API 비용, 참조 이미지 선택 정확도, 긴 장면에서의 메모리 관리에 크게 의존한다.

Usage & Setup

그림 5. ViMax 로컬 실행 절차 요약. 설치보다 중요한 단계는 모델 공급자와 API 키, 작업 디렉터리를 YAML에 정확히 지정하는 것이다.

1. 설치

git clone https://github.com/HKUDS/ViMax.git
cd ViMax
uv sync

2. 모델 설정

configs/idea2video.yaml 또는 configs/script2video.yaml에서 세 가지를 설정한다.

chat_model:
  init_args:
    model: google/gemini-2.5-flash-lite-preview-09-2025
    model_provider: openai
    api_key: YOUR_KEY
    base_url: https://openrouter.ai/api/v1

image_generator:
  class_path: tools.ImageGeneratorNanobananaGoogleAPI
  init_args:
    api_key: YOUR_KEY

video_generator:
  class_path: tools.VideoGeneratorVeoGoogleAPI
  init_args:
    api_key: YOUR_KEY

working_dir: .working_dir/idea2video

 

MiniMax를 사용할 경우에는 model_provider: minimax와 MINIMAX_API_KEY 환경변수를 사용할 수 있다.

export MINIMAX_API_KEY="..."

3. 실행

uv run python main_idea2video.py
uv run python main_script2video.py

실제 운영에서는 다음을 별도로 관리하는 편이 안전하다.

• 장면 수, 샷 수, 동시 생성 수에 따른 API 비용 상한
• working_dir 정리 정책
• 실패한 샷만 재실행하는 resume 기능
• 캐릭터·배경 일관성 자동 평가 지표

Personal Insights

의료 AI 관점

ViMax의 구조는 의료 교육용 시뮬레이션, 환자 여정 설명 영상, 술기 교육용 장면 재구성에 응용 가능성이 있다. 예를 들어 “응급실 내원 → 문진 → 검사 → 처치 → 퇴원 교육” 같은 임상 플로를 장면 단위로 나누고, 의료진·환자·보호자의 역할을 일관되게 유지하는 영상 스토리보드로 만들 수 있다. 다만 의료 영역에서는 환자 정보 보호, 환각 방지, 임상 지침 준수, 위험한 처치 묘사 제한이 필수이므로, 현 상태 그대로 제품화하기보다는 검증 계층과 전문가 승인 워크플로가 필요하다.

Bioinformatics 관점

생물정보학에서는 논문, pathway 설명, 실험 프로토콜, multi-omics 분석 결과를 설명형 영상으로 바꾸는 데 유사한 구조를 적용할 수 있다. 긴 텍스트를 장면·이벤트·객체로 분해하고, 각 장면에 적합한 시각 참조를 선택하는 방식은 “문헌 기반 pathway animation”이나 “분석 리포트 자동 시각화”에 맞는다. 단, 유전자·단백질·세포 유형 같은 도메인 엔티티를 정확히 유지하려면 일반 캐릭터 추출기 대신 ontology-aware entity extractor가 필요하다.

Autonomous Agent 개발 관점

ViMax는 단일 거대 프롬프트보다 역할 분해 + 중간 산출물 + 공급자 추상화 + rate limit 관리가 실용적이라는 점을 잘 보여준다. 에이전트 시스템을 설계할 때는 “누가 무엇을 결정하는가”뿐 아니라 “결정 결과가 어디에 저장되고, 다음 단계가 어떻게 재사용하는가”가 중요하다. ViMax에서 더 보강하면 좋은 지점은 다음과 같다.

• 예산 기반 scheduler: 장면·샷별 예상 API 비용을 계산하고 상한을 넘으면 중단
• deterministic artifact graph: 각 프레임·클립이 어떤 프롬프트와 참조 이미지에서 나왔는지 추적
• 자동 평가: 캐릭터 identity, 배경 consistency, shot continuity, narrative coverage 지표화
• human-in-the-loop 편집: 스토리보드 승인 후 생성 단계로 넘어가는 체크포인트
• resume/retry: 실패한 샷만 재생성하는 DAG 실행기

이미지 자산 매핑

파일	의미	문서 내 배치
figures/ViMax_프로젝트_배너.png	저장소 공식 배너, 프로젝트 정체성 소개	서두
figures/ViMax_Script2Video_처리_파이프라인.png	스크립트 입력이 샷 클립으로 변환되는 과정	Key Features
figures/ViMax_참조이미지_연속성_제어.png	캐릭터·배경 일관성 제어 방식	Key Features
figures/ViMax_멀티에이전트_아키텍처.png	멀티 에이전트 전체 시스템 구조	Architecture
figures/ViMax_로컬실행_요약.png	설치·설정·실행 흐름	Usage & Setup

분석 기준

• README 및 Quick Start: readme.md
• 핵심 파이프라인: pipelines/idea2video_pipeline.py, pipelines/script2video_pipeline.py
• 설정 구조: configs/idea2video.yaml, configs/script2video.yaml
• 공급자 추상화: tools/render_backend.py, utils/provider_presets.py
• 주요 에이전트: agents/storyboard_artist.py, agents/reference_image_selector.py