vox-director

这是什么？适合谁？

Vox Director（MIT，Python + ffmpeg）是一个 Agent Skill（编码代理技能）：你给它一行主题（“给我做一个介绍墨西哥街头美食的 Vox 风格拼贴视频，英文，16:9，15 秒”），它产出一条成品 final.mp4——剧本、纸拼贴关键帧、动效、旁白、配乐、字幕，全程自动化，跑在 Atlas Cloud API + 本地 ffmpeg 上，任何编码 Agent（Claude Code、Codex 等）都能用。

视觉风格是 Vox 解释视频带火的那种现代编辑部纸拼贴（paper-collage）：手剪纸片、撕裂边缘、胶带、半调网点、报纸剪报、每拍一记大字标题——再用动效、旁白、音乐和字幕活起来。

适合谁：

• 用 Claude Code / Codex 的创作者，要批量产出”Vox 风”知识讲解视频、产品广告片、社交媒体短内容
• 内容团队想要一条可复现、可改参数的视频生成流水线，而不是每次手搓 Sora/Veo 抽卡
• 研究”Agent Skill 工程化”的人——它是少数带双人工决策闸门（beat map 审批 + 风格盲选）的完整六阶段流水线范本

不适合谁：

• 想要真人实拍剪辑的（这是生成式拼贴动画，不是剪辑器；剪辑需求看 FableCut）
• 没有编码 Agent、不想办 API Key 的纯手动用户
• 对视频里出现真实人脸/品牌有合规顾虑又不懂换模型路由的（默认路径外有专门路由，见踩坑 5）

使用前提：一个编码 Agent（Claude Code / Codex）；Atlas Cloud API Key；ffmpeg + ffprobe；Python 3 + Pillow（字幕/水印覆盖层用）。

准备工作

1. 环境：编码 Agent；Atlas Cloud 账号（console/api-keys）；ffmpeg + ffprobe（brew install ffmpeg 或平台等价命令）；Python 3 + pip install pillow
2. 获取：git clone https://github.com/Alisa0808/vox-director.git ~/.claude/skills/vox-director（或下载 vox-director.skill 包走 Claude 技能 UI 安装）
3. 成本：Skill 本身 MIT 免费；运行成本 = Atlas Cloud API 调用（关键帧出图、图生视频、TTS、音乐生成，一条 30-60 秒视频要过 6 个模型多次调用——具体单价以 Atlas Cloud 定价 为准，本站未核验具体金额，用前自己看一眼）
4. 时间：装技能 5 分钟；跑通第一条片（含两道人工闸门确认）约 20-40 分钟
5. 前置知识：会用命令行和编码 Agent；懂”API Key 环境变量”；英文 prompt 表述（SKILL.md 为英文，中文入口在 SKILL.zh.md）
6. 替代方案：手搓多模型管线（Sora/Veo + ElevenLabs + 剪辑，无闸门无流水线）；Higgsfield 等拼贴广告商用工具（闭源模板）；直接用剪映模板（非程序化）

快速上手（3 步）

第一步：安装技能

git clone https://github.com/Alisa0808/vox-director.git ~/.claude/skills/vox-director

或下载打包的 vox-director.skill 从 Claude 技能 UI 装。Claude Code 会自动发现它；Codex 等其他 Agent 从 AGENTS.md → SKILL.md 入口读。

然后设置 API Key：

export ATLASCLOUD_API_KEY="sk-..."

预期产出：Agent 技能列表里出现 vox-director。

第二步：一句话下单

对装好技能的编码 Agent 说：

“Make me a Vox-style collage video introducing Mexican street food — English, 16:9, 15 seconds.”

预期产出：Agent 先给你一份 beat map（叙事节拍图）草案等你审批——这是第一道人工闸门，你确认叙事结构后流水线才继续。

第三步：风格盲选，然后等片

beat map 过审后，技能会把同一拍渲染成 3-4 种主题风格让你凭眼缘挑（第二道人工闸门 GATE 2）。选定后全自动：关键帧（每拍一张拼贴海报）→ 动效（图生视频）→ 旁白 + 配乐 → ffmpeg 组装（拼接、音乐躲让旁白、烧字幕+水印），产出 out/<project>/final.mp4。

预期产出：一条带旁白、配乐、字幕的成品拼贴视频。

流水线全景（为什么它比”抽卡”强）

一个主题每阶段一份脚本驱动，全部挂在每个项目一份 beats.json 上：

topic
  ├─ 1. beat map        选叙事弧 → 写 beats.json        ◀── GATE 1: 你审批节拍图
  ├─ 2. style bake-off  同一拍渲染 3-4 种主题            ◀── GATE 2: 你挑风格
  ├─ 3. keyframes       每拍一张拼贴海报 (nano-banana-2)
  ├─ 4. motion          海报动画化 (gemini-omni-flash i2v)
  ├─ 5. voice + music   旁白 (xai/tts) + BGM (minimax/music)
  └─ 6. assemble        ffmpeg: 拼接、音乐躲让、字幕水印
  → final.mp4

两条核心设计判断（README 原话）：

1. 风格诞生于出图那一步：每一拍是一张完成度完整的拼贴海报，所有拼贴 DNA（撕纸、剪纸、半调、标题字）都在那张图里——海报不够”拼贴”，下游救不回来。
2. 动效是后加的：默认用 AI 视频模型整张动画化（“活海报”路径）；要戏剧性的逐件拼装效果，可选本地关键帧引擎把海报切成零件逐帧驱动（无内容过滤、像素级精确——适合真人素材）。

除 B-roll（主题进、全生成）外还有两种输入模式复用同一引擎：

• A-roll：你已有一条真人出镜口播视频——ASR 切成节拍后重风格化为拼贴风，保留真人脸、口型与手势逐帧不动（gemini-omni-flash/video-edit，失败自动重试 seedance-2.0/reference-to-video）。
• C-roll：你只有一张静态照片（自拍、产品图）——主体被抠成”照片贴纸”永不重绘，每拍海报围绕它生成（nano-banana-2/edit），旁白还能克隆成照片本人的声音。

常见踩坑（症状 → 原因 → 解决）

1. 模型 ID 报错 / 调用 404。症状：脚本喊找不到 google/nano-banana-2/text-to-image。原因：README 明说 “Model IDs drift”。解决：这不是你的问题——技能在跑之前会先从 GET https://api.atlascloud.ai/api/v1/models 拉实时模型列表自动适配；如果仍失败，检查 API Key 与账户额度。
2. 成片”不够 Vox”。症状：观感像普通幻灯片。原因：违反了它自己的第一设计律——风格诞生于出图那一步，关键帧海报本身拼贴元素不够（撕边/剪纸/半调/大标题缺项）。解决：回到 GATE 2 重选风格主题，或改 references/prompt-guide.md 里的 LOOK 层措辞强化拼贴词汇；别指望动效阶段补救。
3. 真人/品牌内容被内容过滤拦。原因：默认动效走 gemini-omni-flash/image-to-video，真人/品牌有合规路由。解决：README 给了专门路由——真人/品牌动画化用 kwaivgi/kling-video-o3-pro/image-to-video，或走本地关键帧引擎（无内容过滤、逐件拼装路径，官方标注”great for real people”）。
4. 烧字幕/水印步骤崩溃。症状：第 6 阶段 ffmpeg 或 Python 报错。原因：缺 Pillow 或 ffmpeg/ffprobe 不在 PATH。解决：pip install pillow + brew install ffmpeg（或平台等价）；ffprobe 也必须装，别只装 ffmpeg。
5. API 账单超预期。原因：一条片过 6 个模型多次调用（每拍一张海报 + 每拍一次 i2v + TTS 全文 + 音乐整曲），15 秒短片的调用次数没有想象中少。解决：先用 15 秒短主题试跑估算单条成本再批量；beat 数控制在叙事最低够用；beats.json 可手工编辑砍拍。
6. 技能没被 Agent 发现。原因：clone 到了错误目录，或非 Claude Agent 没读到入口。解决：Claude Code 必须放 ~/.claude/skills/vox-director（自动发现）；Codex 等其他 Agent 要从仓库根 AGENTS.md 引导到 SKILL.md——在首个 prompt 里显式点名技能。

初级用法

• 改 beats.json 而不是重下prompt：每次生成后项目目录里的 beats.json 是唯一事实源——改叙事结构直接编辑它再续跑，不用从主题重头再来。
• 先跑 examples：examples/ 里有现成可跑的 beats.json（含 showcase 影片的节拍数据），先跑一条建立”节拍-时长-节奏”的直觉。
• 限定时长与语言：prompt 里显式写 “English, 16:9, 15 seconds” 这类约束，比事后抱怨成片太长有效。

高级玩法

• A-roll 真人改造流水线：拿一条库存口播视频批量转拼贴风——真人脸和口型逐帧保留，旧内容资产低成本翻新成新视觉风格。
• C-roll 产品图变广告：一张产品静态图 → 照片贴纸嵌进每拍海报 + 声音克隆旁白，做电商投放素材的批量变体（不同节拍图 × 不同旁白文案）。
• 本地关键帧引擎做逐件拼装：references/local-engine.md 的进阶路径把海报切零件逐帧驱动——绕开内容过滤的同时拿到戏剧性的手工拼贴动画感，真人素材首选。
• 读 references/ 学流水线设计：prompt-guide.md（LOOK 层提示词结构与 9 套主题预设）、beat-layer.md（14 种叙事弧 + 钩子/节奏/镜头模式）、models-and-gotchas.md（把 API/ffmpeg 的坑预先踩平）、voices.md（按语言/语气挑 voice_id）——照这套结构给自己的领域写同构技能。

小技巧

1. 两道闸门是省钱的：beat map 审批在你花一分钱出图之前；风格盲选只渲染一拍。别为了快跳过它们。
2. 声音选择有清单：references/voices.md 按语言/语气给了 xai/tts 的 voice_id 名册，别用默认音色凑合。
3. out/<project>/ 目录里中间产物（每拍海报、动效片段）都保留着——单拍不满意只重跑那一拍的脚本，不用整条重来。
4. 音乐躲让（duck under VO）是 ffmpeg 阶段自动做的，但如果旁白密度特别高，在 beat map 阶段就少写几拍，别指望后期混音救。
5. 中文用户读 SKILL.zh.md（仓库自带中文版技能定义），但注意 README 说中英入口内容同构，跑的脚本链是同一条。

常见问题 FAQ

Q1: 它和直接用 Sora / Veo 生成视频有什么区别？

A: 抽卡 vs 流水线。文生视频模型一次给一条不可分解的成品，改一拍要重抽整条；vox-director 把视频拆成节拍图驱动的六阶段流水线——叙事、风格、关键帧、动效、声音、组装各自独立可控可复跑，还有两道人工闸门卡住大方向。代价是要接一串模型 API 而不是一个输入框。

Q2: 不用 Claude Code 能跑吗？

A: 能。它是客户端中立的 Agent Skill：Codex 等任意能读工作流、跑脚本的编码 Agent 从 AGENTS.md → SKILL.md 入口接入；硬性依赖是 Atlas Cloud API Key 和本地 ffmpeg/Python 环境，不是特定 Agent 品牌。

Q3: 一定要 Atlas Cloud 吗？能不能换别家 API？

A: 官方验证过的模型路由全部是 Atlas Cloud 上的 ID（nano-banana-2 / gemini-omni-flash / kling-o3-pro / xai-tts / seed-audio / minimax-music），技能还会在运行前拉 Atlas 的实时模型列表自适配。换供应商等于自己改整条模型路由层——references/models-and-gotchas.md 把坑写平了，但工程量自负。

Q4: 一条视频大概多少钱？

A: 本站未核验具体单价：成本结构 = 每拍一次文生图 + 每拍一次图生视频 + 整篇 TTS + 整曲音乐生成，模型单价以 Atlas Cloud 控制台为准。建议先跑 15 秒短主题实测自己的单条成本再批量投产。

Q5: 生成的视频版权/商用怎么办？

A: Skill 代码 MIT；但成片内容的权利取决于底层生成模型（Google/Kling/MiniMax/xAI 等）的输出条款与你的 Atlas Cloud 订阅协议——商用前逐模型确认，特别是含真人克隆声音（bytedance/seed-audio-1.0）与真人形象改制的 A/C-roll 内容。

Q6: 为什么我的成片节奏感不如 showcase？

A: showcase 片的节拍数据在 examples/ 里可以直接对照——节奏差距多数出在 beat map 的叙事弧选择和钩子密度（references/beat-layer.md 的 14 弧 + 钩子/步调模式就是为此准备的），而不是出在生成模型。

免责声明

本文基于公开资料整理（GitHub README 英文全文与仓库 API 元数据，核验日期 2026-09-15），AI 辅助生成，未在本站环境实际运行该技能或生成视频。模型 ID、闸门行为、成本量级以官方 README 与 Atlas Cloud 实时接口为准；成片商用版权问题需逐模型自查，本文不构成法律意见。

参考链接

• GitHub 仓库 Alisa0808/vox-director
• SKILL.md（技能工作流定义）
• AGENTS.md（非 Claude Agent 入口）
• SKILL.zh.md（中文技能定义）
• Atlas Cloud API Keys
• showcase 影片集（仓库 assets）