安装

VEA 是开源的！请从 GitHub 获取：

# 克隆仓库
git clone https://github.com/Memories-ai-labs/vea-open-source.git
cd vea-open-source

# 安装 uv 包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装依赖
uv sync
source .venv/bin/activate

# 复制配置文件并添加你的 API 密钥
cp config.example.json config.json

📄 论文: https://arxiv.org/abs/2509.16811

💻 代码: https://github.com/Memories-ai-labs/vea-open-source

系统要求

• Python 3.11+
• FFmpeg - 必须在系统中安装
• uv - 包管理器（已在上一步安装）
• API 密钥（位于 config.json 中）：

- MEMORIES_API_KEY（必需） - 视频索引与理解 - 在 https://memories.ai/app/service/key 获取

- GOOGLE_API_KEY（必需） - 脚本生成 - Google Cloud Console

- ELEVENLABS_API_KEY（必需） - TTS 语音旁白与字幕

- SOUNDSTRIPE_KEY（可选） - 背景音乐选择

安装 FFmpeg

启动服务端

gcloud auth application-default login  # 认证 GCP
source .venv/bin/activate
python -m src.app

服务运行在 http://localhost:8000

隐私说明

• 视频由 VEA 服务端本地处理
• 视频帧发送至 Memories.ai 进行 AI 理解
• ElevenLabs 接收文本用于 TTS 语音合成
• 所有中间文件本地存储于 data/outputs/

视频编辑代理（VEA）

本地视频编辑服务，地址为 http://localhost:8000。运行路径为 ~/vea。

⚠️ 用户交互流程（必须遵循）

在处理任何视频编辑请求前，请显示配置选项并等待确认：

📹 VEA 视频编辑配置

🎬 源视频: [视频路径/名称]
📝 编辑请求: [用户输入的提示]

请确认以下设置：
┌─────────────────┬────────┬─────────────────────────┐
│ 设置            │ 值     │ 说明                    │
├─────────────────┼────────┼─────────────────────────┤
│ 🔊 原始音频        │ ❌ 关闭 │ 保留原始视频音轨         │
│ 🎤 语音旁白        │ ✅ 开启 │ AI 生成语音旁白          │
│ 🎵 背景音乐        │ ✅ 开启 │ 自动从 Soundstripe 选取   │
│ 📝 字幕            │ ✅ 开启 │ 自动生成并嵌入画面       │
│ 📐 画面比例        │ 16:9   │ 16:9 横屏 / 9:16 竖屏 / 1:1 方形 │
│ 🎼 同步节拍        │ ❌ 关闭 │ 切剪同步背景音乐节拍     │
└─────────────────┴────────┴─────────────────────────┘

回复 "confirm" 开始编辑，或告诉我需要调整哪些设置。

默认设置：

• original_audio: false（关闭原始音频，使用旁白替代）
• narration: true（启用 AI 语音旁白）
• music: true（启用背景音乐）
• subtitles: true（启用字幕）
• aspect_ratio: 1.78（16:9 横屏）
• snap_to_beat: false（不启用节拍同步）

画面比例选项：

• 16:9（1.78）— 横屏，适用于 YouTube
• 9:16（0.5625）— 竖屏，适用于 TikTok/Reels
• 1:1（1.0）— 方形，适用于 Instagram

快速开始

# 启动 VEA 服务端（建议使用 tmux 处理长时间任务）
cd ~/vea && source .venv/bin/activate && python src/app.py

核心工作流

1. 索引视频（编辑前必做步骤）

在进行任何编辑前，需先对视频进行索引以启用 AI 理解功能：

curl -X POST "http://localhost:8000/video-edit/v1/index" \
  -H "Content-Type: application/json" \
  -d '{"blob_path": "data/videos/PROJECT_NAME/video.mp4"}'

将生成 ~/vea/data/indexing/PROJECT_NAME/media_indexing.json 文件。

2. 生成精彩片段

curl -X POST "http://localhost:8000/video-edit/v1/flexible_respond" \
  -H "Content-Type: application/json" \
  -d '{
    "blob_path": "data/videos/PROJECT_NAME/video.mp4",
    "prompt": "创建一个 1 分钟的最佳时刻精彩片段",
    "video_response": true,
    "original_audio": false,
    "music": true,
    "narration": true,
    "aspect_ratio": 1.78,
    "subtitles": true
  }'

参数说明：

• video_response: true — 生成视频输出（而非仅文本）
• original_audio: false — 关闭原始音频，使用旁白
• music: true — 添加背景音乐（需 Soundstripe API）
• narration: true — 生成 AI 语音旁白（ElevenLabs）
• subtitles: true — 将字幕嵌入视频
• aspect_ratio — 1.78（16:9）、1.0（方形）、0.5625（9:16 竖屏）

3. 手动视频合成

如需更多控制，可使用辅助脚本：

# 为已有视频添加背景音乐
python ~/vea/scripts/add_soundstripe_music.py

# 生成带字幕的视频
python ~/vea/scripts/add_music_subtitles.py

目录结构

~/vea/
├── data/
│   ├── videos/PROJECT_NAME/      # 源视频
│   ├── indexing/PROJECT_NAME/    # media_indexing.json
│   └── outputs/PROJECT_NAME/     # 最终输出
│       ├── PROJECT_NAME.mp4      # 最终视频
│       ├── clip_plan.json        # 片段时间戳 + 旁白内容
│       ├── narrations/           # TTS 音频文件
│       ├── subtitles/            # SRT 字幕文件
│       └── music/                # 背景音乐文件
├── config.json                   # API 密钥配置文件
└── src/app.py                    # FastAPI 服务主程序

API 密钥（位于 config.json）

常见问题

“ViNet 资源未找到” — 动态裁剪功能已禁用。请在 config.json 中设置 enable_dynamic_cropping: false。

API 调用失败但手动运行正常 — 建议在 tmux 中运行服务端以保持环境完整。

音乐下载返回 401/403 错误 — 请检查 Soundstripe API 密钥是否有效。

剪辑时间戳错误 — 请确保设置 original_audio: true，以通过语音转录功能实现时间戳优化。

手动添加音乐

当 Soundstripe 无法使用时，可手动下载并混合音频：

# 从 Soundstripe API 下载
SOUNDSTRIPE_KEY=$(jq -r '.api_keys.SOUNDSTRIPE_KEY' ~/vea/config.json)
curl -s "https://api.soundstripe.com/v1/songs/TRACK_ID" \
  -H "Authorization: Token $SOUNDSTRIPE_KEY" | jq '.included[0].attributes.versions.mp3'

# 使用 ffmpeg 混合（音乐音量设为 15-20%）
ffmpeg -y -i video.mp4 -i music.mp3 \
  -filter_complex "[1:a]volume=0.18,afade=t=out:st=70:d=4[m];[0:a][m]amix=inputs=2:duration=first[a]" \
  -map 0:v -map "[a]" -c:v copy -c:a aac output.mp4

参考资料

• [API 文档](references/api.md) — 完整的接口规范
• [配置 Schema](references/config.md) — 配置选项说明