本项目面向比赛评审演示：输入一条爆款样例视频，系统拆解样例的脚本结构、镜头节奏和素材槽位，再迁移到一个新的商品主题，完成素材缺口判断、候选素材复用、AIGC 缺口补片规划、时间线生成、质检和 Remotion 竖屏 MP4 输出。

评审重点不是“用外部模型黑盒生成整条视频”，而是展示一条可验证的创作链路：

样例视频 -> 结构抽取 -> 新主题迁移 -> 素材适配 -> 成片渲染 -> 证据链审计

请先安装：

• Node.js 20 或更高版本
• npm
• Python 3.10 或更高版本
• FFmpeg，并确保 ffprobe 能在命令行中直接运行

Windows 下可用以下命令检查：

node --version
npm --version
python --version
where.exe ffprobe
ffprobe -version

请务必在 .env 中FFMPEG_BIN_DIR单独配置ffprobe安装路径！！！

FFMPEG_BIN_DIR=C:\ffmpeg\bin

在项目根目录执行：

npm install

安装视频分析依赖：

python -m pip install -r apps/api/requirements-video.txt

说明：Whisper 首次转写会下载本地模型，第一次分析带语音的视频可能较慢；如果转写失败，系统会保留已完成的元数据和镜头切分结果并给出降级提示。

复制模板：

Copy-Item .env.example .env

macOS / Linux 可用：

cp .env.example .env

把给定的key放入：

LLM_API_KEY=填入 DeepSeek Key
GROK_API_KEY=填入 ToAPIs Grok Video Key

其中 LLM_API_KEY 是 DeepSeek 文本模型 Key，用于结构迁移和脚本规划；GROK_API_KEY 是 ToAPIs Grok Video Key，只用于生成缺口短素材。

如果页面提示 DeepSeek API Key 认证失败 或 HTTP 401，说明后端已经连到 DeepSeek，但 Key 没通过认证。请按下面检查：

• .env 必须放在项目根目录，也就是和 package.json 同级。
• LLM_API_KEY 必须填写 DeepSeek 开放平台生成的 API Key，不是 Grok / ToAPIs Key。
• Key 要完整粘贴在同一行，前后不要有空格或换行。
• LLM_BASE_URL=https://api.deepseek.com
• LLM_MODEL=deepseek-v4-pro
• 保存 .env 后必须停止并重新执行 npm run dev。

真实 AIGC 生成需要当前电脑能通过普通网络访问 ToAPIs。评审运行时不需要配置代理，可先测试：

curl.exe -I https://toapis.com

如果提示“视频已生成，但本机下载生成文件失败”，说明任务已经完成，但当前网络无法稳定下载 files.toapis.com 上的 mp4。可测试：

curl.exe -I https://files.toapis.com

项目默认把生成视频下载窗口限制为 30 秒，避免新电脑网络不通时页面长时间卡住；如果网络较慢但能访问，可在 .env 中把 GROK_DOWNLOAD_TIMEOUT_MS 调到 60000 或 90000 后重启后端。

GROK_PROXY_URL 不是评审必填项，仅用于开发机网络排查。普通网络可直连时保持为空；后端不会读取 HTTP_PROXY 或 HTTPS_PROXY。如果开发机确实需要代理，可临时配置：

GROK_PROXY_URL=http://127.0.0.1:7897

配置后重启 npm run dev。未配置代理时，也可以取消页面里的“允许真实 AIGC 生成素材”，走 mock 生成闭环。

npm run dev

默认地址：

• 前端：http://127.0.0.1:5173
• 后端健康检查：http://127.0.0.1:4000/api/health
• Mock Video DNA：http://127.0.0.1:4000/api/video-dna/mock

PowerShell 如果拦截 npm.ps1，可改用：

npm.cmd run dev

从 GitHub 拉下来的代码可以直接安装、配置 .env 并启动。为了避免提交大文件、原始素材、生成缓存和密钥，仓库不会提交以下目录：

• video/
• data/uploads/
• data/outputs/
• data/render-assets/
• data/aigc-generated-videos/
• data/material-library/

这些目录是本地运行资产目录，不是代码依赖。项目启动时会自动创建需要的运行目录。

如果拿到的是完整本地交付包，video/ 目录中的演示素材会被系统直接读取；如果只从 GitHub clone 代码，也可以上传任意本地 MP4 作为样例视频继续体验主流程。没有本地素材库时，系统仍可展示样例解析、结构迁移、缺口判断、mock AIGC 闭环和图形包装；素材候选会根据本机实际素材情况显示。

本地素材库使用 video/library/，文件名前缀用于判断素材槽位：