ViMax 是一个智能体视频生成框架，集成了导演、编剧、制片和视频生成能力

ViMax 是一个智能体视频生成框架，集成了导演、编剧、制片和视频生成能力，能将一个简单的想法或脚本转化为完整的视频。

本教程将覆盖从环境准备到使用其交互式界面（TUI和Web UI）和核心管道的完整流程。

📥 第一步：环境准备与安装

ViMax 使用 uv 作为主要的包管理工具，以确保环境一致性。

安装 uv：如果尚未安装，请参照 uv 官方安装指南进行安装。
克隆并同步项目：
1
2
3
git clone https://github.com/HKUDS/ViMax.git
cd ViMax
uv sync
该命令会创建一个虚拟环境并安装所有必需的Python依赖。

🤖 第二步：配置API密钥（核心步骤）

ViMax 依赖外部AI服务来完成视频生成的各个环节，因此需要配置相应的API密钥。这些配置应用于不同的使用方式。

配置文件位置：无论是终端TUI、Web UI还是直接运行管道脚本，配置方式一致，都是通过编辑 configs/agent.local.yaml 文件或设置环境变量。

创建本地配置文件：

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

编辑配置文件：在 configs/agent.local.yaml 中，填入你的模型提供商、模型名称、Base URL和API Key。该文件通常需要配置 LLM（大语言模型）、图像生成模型 和 视频生成模型 三部分。例如，使用OpenRouter的配置示例如下：

llm:
  model_provider: openai  # 或其他兼容OpenAI API的提供商
  model: google/gemini-2.5-flash-lite-preview-09-2025
  base_url: https://openrouter.ai/api/v1
  api_key: <你的API_KEY>

image:
  model: <你的图像模型>
  base_url: <图像服务Base URL>
  api_key: <你的API_KEY>

video:
  model: <你的视频模型>
  base_url: <视频服务Base URL>
  api_key: <你的API_KEY>

备选方案：你也可以不编辑此文件，而通过设置环境变量（如 VIMAX_LLM_API_KEY, VIMAX_IMAGE_API_KEY, VIMAX_VIDEO_API_KEY）来提供密钥，这样更安全。

🖥️ 第三步：启动交互式界面 (TUI 或 Web UI)

ViMax 提供了两种交互式工作空间，用于规划、修订和监控视频生成过程。

方式一：启动终端TUI
在 ViMax 项目根目录下，运行以下命令之一：

# 启动一个新会话
vimax tui new

# 恢复上一个会话
vimax tui resume

# 恢复指定ID的会话
vimax tui resume <session_id>

方式二：启动Web UI（推荐）
Web UI 提供了更丰富的图形化体验，支持项目文件管理、实时预览生成进度等。

安装前端依赖并启动服务：
1
2
3
cd web
npm install
npm run dev
访问界面：在浏览器中打开 http://127.0.0.1:4173。
远程访问：如果ViMax部署在远程服务器上，可以通过SSH端口转发在本地访问：
1
ssh -N -L 4173:127.0.0.1:4173 <用户名>@<服务器地址>

🎬 第四步：运行核心视频生成管道

除了交互式界面，你也可以直接运行特定的Python脚本来生成视频。

1. Idea2Video (想法生成视频)
将你的一个简短想法转化为完整的视频。

配置：编辑 configs/idea2video.yaml 文件，配置其中的 chat_model, image_generator, video_generator 部分的API信息。
修改创意：在 main_idea2video.py 文件中，找到并修改 idea, user_requirement, style 等变量。
运行：python main_idea2video.py

2. Script2Video (脚本生成视频)
根据你提供的详细脚本生成视频。

配置：编辑 configs/script2video.yaml 文件，配置API信息。
修改脚本：在 main_script2video.py 文件中，替换 script, user_requirement, style 变量的内容。
运行：python main_script2video.py

💡 关键要点与提示

核心优势：ViMax 通过智能体工作流解决了AI视频生成的三大难题——时长限制、一致性（角色/场景）和叙事深度（脚本/音频）。它能够自主完成从创意到故事板再到最终视频的复杂流程。
模型支持：项目在持续更新，已支持多种模型提供商，如 OpenRouter（集成多种模型）、Google Gemini/Veo、MiniMax、Seedance 等。请关注项目README的“News”部分以获取最新支持信息。
并行生成：ViMax支持并行生成多个镜头和媒体资产，能显著加速多镜头视频的生产。
显存与性能：具体的硬件要求取决于你使用的图像/视频生成模型。本地运行某些模型（如ComfyUI工作流）可能需要较高配置的GPU，而使用云API则只需稳定的网络连接。