🖥️ Environment

OS: Linux, Windows

📥 Clone and Install

We use uv to manage the environment. For uv installation, please refer to the https://docs.astral.sh/uv/getting-started/installation/.

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

<details> <summary><strong>Agent TUI</strong></summary>

ViMax also provides a minimal TUI for interactive agent-based video creation. Create a private local configuration from the tracked example first:

cp configs/agent.example.yaml configs/agent.local.yaml

Then configure the model and API key information in configs/agent.local.yaml, including the LLM, image generator, and video generator, as shown below.

llm:
  model_provider: openai
  model: <YOUR_LLM_MODEL>
  base_url: <YOUR_LLM_BASE_URL>
  api_key: <YOUR_API_KEY>

image:
  model: <YOUR_IMAGE_MODEL>
  base_url: <YOUR_IMAGE_BASE_URL>
  api_key: <YOUR_API_KEY>

video:
  model: <YOUR_VIDEO_MODEL>
  base_url: <YOUR_VIDEO_BASE_URL>
  api_key: <YOUR_API_KEY>

Then, start the TUI from the ViMax root directory:

vimax tui

Start a new session or resume an existing one:

vimax tui new
vimax tui resume
vimax tui resume <session_id>

You can also keep configs/agent.local.yaml empty and provide the same values through environment variables, such as VIMAX_LLM_API_KEY, VIMAX_IMAGE_API_KEY, and VIMAX_VIDEO_API_KEY.

</details> <details> <summary><strong>Web UI</strong></summary>

The Web UI uses the same ViMax agent runtime, sessions, tools, and private configs/agent.local.yaml configuration as the TUI. Node.js 18 or newer is required.

From the ViMax repository root, install the frontend dependencies once and start the local server:

cd web
npm install
npm run dev

Open http://127.0.0.1:4173 in your browser. The Web UI supports named projects, agent conversations, slash commands, artifact and render inspection, storyboard previews, file uploads, and provider settings.

The server binds to 127.0.0.1 by default. When ViMax runs on a remote machine, forward the port from your local computer:

ssh -N -L 4173:127.0.0.1:4173 <user>@<server>

Use VIMAX_WEB_PORT when another local port is required:

VIMAX_WEB_PORT=4174 npm run dev

</details> <details> <summary><strong>Usage</strong></summary>

Image Selection

ViMax generates 2 keyframe candidates in parallel and selects one using your vision-capable chat model. This can improve visual quality and consistency, at a higher API cost. Set in your YAML config:

image_selection:
  num_candidates: 2 # Set to 1 to disable selection.

main_idea2video.py is used to convert your ideas into videos. You need to configure the model and API key information in the configs/idea2video.yaml file, including three parts—the chat model, the image generator, and the video generator, as shown below

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

image_generator:
  class_path: tools.ImageGeneratorNanobananaGoogleAPI
  init_args:
    api_key: <YOUR_API_KEY>

video_generator:
  class_path: tools.VideoGeneratorVeoGoogleAPI
  init_args:
    api_key: <YOUR_API_KEY>

working_dir: .working_dir/idea2video

Then, provide a simple yet thoughtful idea and the corresponding creative requirements in main_idea2video.py.

idea = \
"""
If a cat and a dog are best friends, what would happen when they meet a new cat?
"""
user_requirement = \
"""
For children, do not exceed 3 scenes.
"""
style = "Cartoon"

main_script2video.py generates a video based on a specific script. You similarly need to set up the API configuration in configs/script2video.yaml file. Then, provide a scene script and the corresponding creative requirements in main_script2video.py, as shown below.

script = \
"""
EXT. SCHOOL GYM - DAY
A group of students are practicing basketball in the gym. The gym is large and open, with a basketball hoop at one end and a large crowd of spectators at the other end. John (18, male, tall, athletic) is the star player, and he is practicing his dribble and shot. Jane (17, female, short, athletic) is the assistant coach, and she is helping John with his practice. The other students are watching the practice and cheering for John.
John: (dribbling the ball) I'm going to score a basket!
Jane: (smiling) Good job, John!
John: (shooting the ball) Yes!
...
"""
user_requirement = \
"""
Fast-paced with no more than 20 shots.
"""
style = "Animate Style"

</details>