HKUDS/ViMax

"ViMax: Agentic Video Generation (Director, Screenwriter, Producer, and Video Generator All-in-One)"

📽️ ViMax – 에이전트 기반 엔드투엔드 비디오 생성

무엇인가요 – ViMax는 단순한 텍스트 아이디어(또는 완전한 스크립트)에서 완성된 비디오까지 도달할 수 있는 오픈소스 프레임워크입니다. 별도의 도구들을 조합할 필요 없이 가능합니다. 이는 LLM 기반 에이전트의 루프를 실행함으로써 이루어집니다. 에이전트는 스크립트 작성, 스토리보드 설계, 일관된 캐릭터 이미지 생성, 마지막으로 AI 비디오 생성기를 호출합니다. 전체 파이프라인은 터미널 UI 또는 브라우저 기반 웹 UI에서 제어할 수 있습니다.

✨ 핵심 기능

기능	제공되는 기능
Idea2Video	짧은 개념을 입력하면 ViMax는 스토리 개요, 캐릭터, 스크립트, 촬영 리스트, 스토리보드를 생성하고 짧은 클립을 렌더링합니다.
Script2Video	스크립트를 제공하면 시스템은 촬영 계획을 세우고 시각적 일관성을 유지하며 다중 장면 비디오를 생성합니다.
Novel2Video	더 긴 소설을 에피소드 형식의 비디오로 변환하며, 내러티브 압축과 캐릭터 추적을 처리합니다.
AutoCameo	사람이나 반려동물의 사진을 업로드하면 생성된 스토리 전반에 걸쳐 해당 주제가 일관되게 등장합니다.
에이전트 루프 + TUI	인터랙티브하고 채팅 스타일의 계획이 가능하며, 아이디어를 수정하고 세션을 재개하며 렌더링 상태를 터미널에서 모니터링할 수 있습니다.
웹 UI	이름이 지정된 프로젝트, 아티팩트 및 스토리보드 미리보기, 렌더링 체크포인트, 파일 업로드 및 제공자 설정이 가능한 브라우저 워크스페이스 (다크 모드 지원).
병렬 생성	촬영 및 미디어 자산을 동시에 생성하여 다중 촬영 제작을 가속화합니다.
제공자 독립	HTTP API를 제공하는 모든 LLM, 이미지 모델, 비디오 모델(OpenAI, OpenRouter, Google Gemini, Seedance 등)에 대한 플러그인 지원.

🛠️ 빠른 시작 (Linux / Windows)

# 1️⃣ 리포지토리 복제
git clone https://github.com/HKUDS/ViMax.git && cd ViMax

# 2️⃣ uv로 Python 환경 설치 (pip도 가능)
uv sync   # 가상 환경 생성 및 종속성 설치

터미널 UI 실행

# 예제 설정 파일 복사 후 API 키 입력
cp configs/agent.example.yaml configs/agent.local.yaml
# YAML 편집 – LLM, 이미지, 비디오 모델/제공자 세부 정보 설정
vim configs/agent.local.yaml

# 인터랙티브 TUI 시작
vimax tui          # 새 세션
vimax tui new      # 또는 기존 세션 재개

브라우저 UI 실행

cd web
npm install        # 한 번만 실행 (Node 18+ 필요)
npm run dev        # http://127.0.0.1:4173 에서 개발 서버 시작

백엔드가 원격 머신에서 실행 중인 경우, README에 설명된 대로 SSH로 포트 포워딩을 수행해야 합니다.

📂 예제 워크플로우

Idea2Video – main_idea2video.py를 편집하여 짧은 프롬프트와 선택적 스타일/요구사항을 입력한 후 실행. 스크립트는 configs/idea2video.yaml에서 LLM, 이미지, 비디오 엔드포인트를 읽습니다.
Script2Video – main_script2video.py를 편집하여 완전한 스크립트를 입력하고 스크립트를 실행. 설정은 configs/script2video.yaml에 있습니다. 두 스크립트 모두 생성된 텍스트, 이미지, 스토리보드, 최종 비디오를 저장하는 작업 디렉터리(.working_dir/...)를 생성합니다.

📦 리포지토리 내부 내용

디렉터리 / 파일	목적
`configs/`	LLM, 이미지, 비디오용 3개의 모델 제공자 예제 YAML 파일.
`web/`	React 기반 프론트엔드; `npm run dev`로 UI 제공.
`tools/`	특정 이미지/비디오 API를 래핑하는 Python 클래스 (예: `ImageGeneratorNanobananaGoogleAPI`).
`main_idea2video.py` / `main_script2video.py`	두 가지 주요 파이프라인을 보여주는 최소한의 진입점.
`README.md`	이 문서, 배지, 뉴스, 데모, 빠른 시작 지침 포함.

🚀 최근 주요 업데이트 (README 기준)

v1.2.0 – 이름이 지정된 프로젝트, 아티팩트 미리보기, 렌더링 체크포인트, 다크 모드를 갖춘 웹 UI.
OpenRouter GPT-Image-2-Image 및 Seedance 2.0 고속 비디오 생성 추가.
에이전트 루프 + TUI 통합으로 인터랙티브 계획 및 세션 재사용 가능.
기술 보고서 및 Novel2Video 워크플로우 공개.

🎯 누구에게 적합한가요?

전체 제작 팀을 고용하지 않고 애니메이션 단편을 프로토타이핑하고 싶은 인디 크리에이터.
수업용으로 빠르고 시각화된 스토리 비디오를 원하는 교육자.
다중 모달 LLM 파이프라인(text → 스토리보드 → 비디오)을 탐구하고 있으며 모듈화되고 확장 가능한 코드베이스가 필요한 연구자.
자신의 이미지 또는 비디오 생성 모델을 통합하고 싶은 개발자.

📜 라이선스

MIT – 코드를 자유롭게 사용, 수정, 재배포할 수 있습니다.

📚 추가 정보

ArXiv 논문 – 2606.07649 (버튼에 링크됨).
YouTube 채널 – "AI-Creator-is-here"에서 데모 영상과 튜토리얼 제공.

✅ TL;DR

ViMax는 LLM 기반 계획, 일관된 이미지 생성, AI 비디오 합성 기능을 하나의 에이전트 중심 워크플로우로 통합합니다. 터미널 UI, 현대적인 웹 UI, 그리고 모든 LLM/이미지/비디오 제공자에 대한 플러그인 지원을 갖추고 있어, 스토리 아이디어를 입력하면 완성된 비디오를 받을 수 있습니다. AI 기반 비디오 제작을 훨씬 더 접근 가능하게 만듭니다.