📦 AI 真人口播视频生成器 (video-ai-talking) 详细部署教程

这是一个开源工具，可以让你上传一段真人出镜视频，通过 AI 配音和对口型，生成一段真人口播的竖屏 MP4 视频。所有密钥仅保存在你的浏览器本地，任务和成片也存储在你自己的电脑上，没有云端服务器。

⚙️ 部署前准备

1. 基础环境要求

  • Node.js：版本 20 或更高。你可以通过 node --version 检查。
  • FFmpeg：必须安装，并确保可以在终端中直接运行 ffmpeg 和 ffprobe 命令。
    • macOS：brew install ffmpeg
    • Windows/Linux：请从 FFmpeg 官网下载并配置到系统环境变量 PATH 中。
  • （Linux 可选）Zenity：如果使用 Linux，为了正常使用系统的文件选择器，建议安装 zenity。否则可以通过拖拽文件的方式上传。

2. 需要申请的 API 密钥

在使用前，你需要根据需求申请以下服务的 API 密钥。所有密钥都只在你的浏览器中配置，不会上传。

用途 所需服务/密钥 申请指引 是否必填
AI 对口型 阿里百炼 VideoRetalk API Key (以 sk- 开头) 产品介绍 · 密钥管理 出片必填
AI 配音 (二选一) 阿里百炼 CosyVoice API Key (以 sk- 开头) 同上 “密钥管理” 配音二选一
AI 配音 (二选一) 火山引擎 语音合成 App ID 和 Access Token 产品介绍 · 控制台申请 配音二选一
AI 写文案 (可选) DeepSeek API Key (以 sk- 开头) 开放平台 · 创建 API Key 可选，不填可手写文案

网络要求：你的电脑需要能访问以下接口：

  • 阿里百炼：https://dashscope.aliyuncs.com
  • 火山 TTS：https://openspeech.bytedance.com
  • DeepSeek：https://api.deepseek.com

🚀 部署与启动

方式一：开发模式运行 (推荐日常使用)

这是最直接的启动方式，适合本机使用或开发调试。

  1. 克隆仓库：

    1
    2
    git clone https://github.com/yizhi-chengzi/video-ai-talking.git
    cd video-ai-talking

  2. 配置环境变量 (可选)：

    1
    cp .env.example .env

    .env 文件只用于配置服务端口，千万不要把 API Key 写进去。如果你想完全离线测试所有功能（不走真实 API），可以在 .env 中设置 VAT_MOCK=1。

  3. 安装依赖并启动：

    1
    2
    npm install
    npm run dev

  4. 访问：在浏览器中打开 http://127.0.0.1:5175。

方式二：生产模式运行 (构建后启动)

如果你想把它作为一个本机服务来运行（页面和 API 由同一个地址提供），可以先构建再启动。

1
2
npm run build
npm start

之后访问 http://127.0.0.1:8789 即可。注意：必须先执行 build，否则访问会 404。

📖 首次使用配置

  1. 打开“配置”页面：在应用界面中找到配置入口。
  2. 填写“AI口播对口型配置”：在对应的卡片中填入你在阿里百炼申请的 VideoRetalk API Key。点击“测试”按钮确认连通性。
  3. 填写“AI配音配置”：根据你选择的配音服务（百炼 或 火山），在对应的卡片中填入密钥或 App ID/Token，并测试连通。
  4. （可选）填写“文案配置”：填入 DeepSeek API Key，用于 AI 辅助生成口播文案。

重要：你的密钥仅保存在浏览器的 localStorage 中（键名为 vat.config），不会发送到任何其他服务器。

🎬 生成视频的工作流程

完成配置后，按照以下步骤生成视频：

  1. 添加真人参考视频：在“口播真人视频”区域，上传一段正面、清晰的真人近景视频（无需说话）。可以使用项目 demos/ 目录下的试用视频。
  2. 准备配音：在配音区选择“火山”或“百炼”服务，然后挑选一个音色。
  3. 准备口播文案：
    • AI 生成：选择成片时长（15-60秒），输入主题，让 AI 生成文案。
    • 手动填写：直接输入或粘贴你准备好的文案。
    • （可选）插入素材：在文案的某一句右侧，可以点击画面格，从“视频素材”面板中选择一段本地视频，将该句对应的画面替换成这段素材。
  4. 选择皮肤样式：在画布区域选择你喜欢的字幕和标题样式，可以控制是否在成片中显示标题和字幕。
  5. 开始生成：点击“开始生成”按钮。任务将按顺序执行：配音 → 对口型 → 合成最终 MP4。
  6. 获取成片：生成完成后，你可以在“成片库”中预览、下载或删除生成的视频。

❓ 常见问题与排查

  • 提示“找不到 ffmpeg”：
    • 确保 FFmpeg 已安装，并在终端中执行 ffmpeg -version 和 ffprobe -version 可以正常显示版本信息。
    • macOS 用户可尝试 brew reinstall ffmpeg。
  • 对口型失败：
    • 检查“AI口播对口型配置”中的百炼 VideoRetalk Key 是否正确且已测试通过。
    • 确认网络可以访问 dashscope.aliyuncs.com。
    • 确保参考视频是包含清晰正脸、非侧脸、非远景的片段。
  • TTS 测试失败：
    • 核对当前选择的配音服务（百炼/火山）的凭证是否填写正确。
    • 检查本机是否能访问对应的服务域名（如 openspeech.bytedance.com）。
  • 生成的视频没有中文标题或字幕是方框：
    • 这是因为 FFmpeg 找不到合适的中文字体。项目 templates/fonts.md 文档中提供了解决方案，通常是安装或指定系统中已有的中文字体路径。
  • Linux 下点“选择文件”没反应：
    • 请安装 zenity 包，或直接将文件从文件管理器拖拽到页面上传区域。

💡 开发与贡献

如果你想参与项目开发，可以运行测试和类型检查：

1
2
npm test
npm run typecheck

测试默认不会调用真实的外部 API，也不要求安装 FFmpeg。

贡献前请阅读：CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md 和 DISCLAIMER.md 文件。

🔒 隐私与安全

  • 所有密钥仅存储在浏览器本地 (localStorage)。
  • 任务数据和生成的音频、视频文件存储在项目目录下的 data/ 文件夹中。
  • 出片时，参考视频和配音会临时上传到阿里百炼的官方临时存储（oss://，约48小时有效）供 VideoRetalk 服务处理。详见 docs/privacy.md。
  • 项目中的 .env 文件只用于端口等非敏感配置，请勿将 API Key 写入其中。

更详细的故障排除和功能说明，请查阅项目 官方文档 中的 docs/ 文件夹。