ViMax Studio

ViMax Studio 是一个基于多智能体工作流的 AI 视频生成项目。它把创意、剧本、角色、分镜、参考图和视频生成串成一条端到端流程，目标是让用户从一句想法或一段剧本出发，快速生成结构化、风格一致的视频内容。

仓库里包含两部分：

• ViMax/：核心 Python pipeline、智能体、配置文件和生成工具。
• app.py + vimax_ui.html：一个轻量 Web UI，用于通过浏览器提交创意并查看生成进度、图片和视频结果。

功能亮点

• Idea2Video：从创意描述生成故事、角色、分镜、图片与视频。
• Script2Video：从已有剧本生成分镜和视频片段。
• 多智能体编排：包含编剧、全局信息规划、角色抽取、场景抽取、分镜设计、参考图选择、图像筛选等模块。
• 可插拔生成后端：通过配置文件切换聊天模型、图片生成器和视频生成器。
• Web Studio：提供登录、创意输入、风格选择、任务日志、图片预览和视频预览。
• Docker 部署：内置 Python 3.12、uv、ffmpeg 和必要系统依赖，适合快速运行 Web UI。

项目结构

.
├── Dockerfile
├── app.py
├── vimax_ui.html
└── ViMax
    ├── agents/          # 多智能体模块
    ├── configs/         # pipeline 配置文件
    ├── interfaces/      # 结构化数据定义
    ├── pipelines/       # Idea2Video / Script2Video 等流程
    ├── tools/           # 图片、视频、重排等生成后端
    ├── utils/           # 视频、图片、限流、重试等工具
    ├── tests/           # 测试用例
    ├── main_idea2video.py
    ├── main_script2video.py
    └── pyproject.toml

环境要求

• Python 3.12+
• uv
• ffmpeg
• 可用的模型 API Key

当前默认配置使用：

• Chat model：OpenRouter 兼容接口
• Image generator：Google Nano Banana / Gemini 图片生成相关实现
• Video generator：Google Veo 相关实现

你也可以在 ViMax/configs/*.yaml 中替换成其他已实现的工具类。

快速开始：Docker 运行 Web UI

推荐用 Docker 启动 Studio UI，因为 Dockerfile 已经处理了系统依赖和 /app 路径。

docker build -t vimax-studio .

docker run --rm -p 8080:8080 \
  -e APP_PASSWORD="your-password" \
  -e OPENROUTER_API_KEY="your-openrouter-api-key" \
  -e GOOGLE_API_KEY="your-google-api-key" \
  vimax-studio

启动后访问：

http://localhost:8080

登录密码为 APP_PASSWORD。如果没有设置，默认密码是：

vimax2024

本地运行核心 Pipeline

进入核心项目目录：

cd ViMax
uv sync

编辑配置文件，填入你的 API Key：

ViMax/configs/idea2video.yaml
ViMax/configs/script2video.yaml

运行 Idea2Video：

uv run python main_idea2video.py

运行 Script2Video：

uv run python main_script2video.py

生成结果会输出到配置文件里的 working_dir，例如：

.working_dir/idea2video

配置说明

配置文件主要包含三类后端：

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

image_generator:
  class_path: tools.ImageGeneratorNanobananaGoogleAPI
  init_args:
    api_key:

video_generator:
  class_path: tools.VideoGeneratorVeoGoogleAPI
  init_args:
    api_key:

working_dir: .working_dir/idea2video

每个服务都支持限流配置，例如 max_requests_per_minute 和 max_requests_per_day。如果你接入的服务限制更严格，建议先把这些值调低。

Web API

Web UI 背后提供了几个简单接口：

• POST /api/generate：提交创意、需求和风格，创建生成任务。
• GET /api/status?job_id=...：查询任务状态、日志、图片和视频。
• GET /api/file?path=...：读取生成出来的媒体文件。

出于安全考虑，文件接口只允许访问 /tmp/vimax_working 下的生成文件。

测试

在 ViMax 目录下运行：

uv run pytest

部分集成测试可能需要真实 API Key。没有 Key 时，优先运行不依赖外部服务的单元测试。

常见问题

1. 为什么推荐 Docker 跑 Web UI？

app.py 中的任务执行路径以容器内 /app 为默认工作目录。直接在本地运行 Flask 可以打开页面，但生成任务更适合在 Docker 环境中执行。

2. API Key 应该放在哪里？

Web UI 使用环境变量：

• OPENROUTER_API_KEY
• GOOGLE_API_KEY
• APP_PASSWORD
• SECRET_KEY

CLI pipeline 使用 ViMax/configs/*.yaml 中的 api_key 字段。

3. 生成很慢怎么办？

视频生成通常耗时较长，并且会受到模型服务队列、速率限制和视频长度影响。可以先降低场景数、镜头数，或调低 user_requirement 中的复杂度。

相关文档

• 英文说明：ViMax/readme.md
• 中文说明：ViMax/README_ZH.md
• 社群信息：ViMax/Communication.md

项目参考与版权说明

本仓库参考并基于开源项目 HKUDS/ViMax 进行整理与扩展，保留原项目的目录结构、核心 pipeline、智能体设计和 MIT License 版权声明。

原始 ViMax 项目及其相关代码、文档、图片、演示素材等版权归原作者和贡献者所有。本仓库中的二次整理、Web Studio 封装、部署配置和 README 补充内容由本仓库维护者及贡献者维护。

如果你复用、修改或分发本项目，请遵守 MIT License，并保留原始版权声明和许可文本。

License

本项目使用 MIT License，详见 LICENSE 和 ViMax/LICENSE。