vox-director：把一句话题目变成纸拼贴讲解片的 agent skill

一句话题目到 final.mp4 之间缺的那段工程

做解释类短视频的人大多卡在同一处：镜头语言是清楚的，但把它拆成可执行的步骤很烦。写脚本、找素材、排版、配旁白、压字幕，每一步都有工具，工具之间没有胶水。vox-director 想补的就是这段胶水，它把 Vox 那种纸拼贴视觉风格固定成一套模板，再把从选题到成片的流程写成 agent 可以照着走的 skill。

README 给出的定位很直接：给一句话题目，拿回一个 mp4。目标用户是已经在用编码 agent 的人，Claude Code 和 Codex 都在支持范围内。它不是一个独立应用，没有 GUI，没有服务端，你通过对话让 agent 调用它，产物落在 out/<project>/final.mp4。

风格选择本身值得说一句。纸拼贴这套视觉（手剪纸片、撕边、胶带、半调网点、剪报、每个 beat 一个平涂主色、大号剪字标题）在 Vox 的解释片里被反复使用，特征足够稳定，所以适合做成模板而不是让模型自由发挥。项目把这一点当成前提，而不是当成可调项。

beats.json 是唯一的真相来源

整个流程围绕一个每项目一份的 beats.json 展开，每个阶段读它、改它、产出下一阶段要用的东西。README 画出的数据流是这样的：先做 beat map，选一条叙事弧线并写出 beats.json；然后做 style bake-off，把同一个 beat 用三到四套主题各渲染一遍；接着逐 beat 生成拼贴海报（nano-banana-2），再逐张做动态化（gemini-omni-flash 的图生视频），然后生成一条旁白（xai/tts-v1）和背景音乐（minimax/music-2.6），最后交给 ffmpeg 做拼接、把音乐压到旁白之下、烧上字幕和水印。

这里有两个设计判断，README 明确说它们决定成败。第一，视觉是在图像那一步成型的：每个 beat 必须是一张完整的拼贴海报，撕纸、剪影、半调、标题文字全都长在这张图里，海报不够拼贴，后面任何环节都救不回来。第二，动态是后加的。默认路径是让视频模型把整张海报当作一个整体来动，README 称之为 living poster；如果想要逐块拼装的戏剧感，可以走一条可选的本地关键帧引擎，把海报切成部件逐帧驱动，这条路径不经内容过滤、像素级精确，README 特别提到它适合真人素材。

叙事结构被单独抽出来放在 references/beat-layer.md 里，README 说那里有 14 条叙事弧线，以及 hook、节奏和镜头模式的处理方式。视觉提示词则放在 references/prompt-guide.md，包含提示词结构、词汇表和 9 套主题预设。也就是说，创意部分不是硬编码在脚本里，而是以参考文档的形式交给 agent 阅读。

两个人工关口，和它们背后的取舍

README 把两个 GATE 写进了流程图：GATE 1 是批准 beat map，GATE 2 是肉眼挑选风格。除此之外全自动。

这个安排是有道理的，但也是有代价的。beat map 决定了整条片子的叙事骨架，改它的成本远低于改已经渲染出来的十几张海报，所以放在最前面让人确认是合理的。风格 bake-off 同理，把同一个 beat 用多套主题渲染出来对比，比事后返工便宜。代价是这两步都要人参与，而且 bake-off 意味着同一个 beat 要渲染三到四次，这部分算力是纯开销。如果你想要的是无人值守的批量生产，这两个关口就是流程里最硬的那道墙。

值得注意的是，README 只说了有两个关口，没有说明关口之间的等待时间、bake-off 渲染的并发方式，也没有给出任何耗时或成本数据。这些只能自己在实际跑的时候观察。

A-roll 与 C-roll：同一台引擎的另外两个入口

除了纯生成（README 叫 B-roll），项目还复用了同一套引擎处理两种已有素材。

A-roll 针对已经有口播视频的情况。流程先做 ASR 把视频切成 beat，再整体重制成拼贴风格，但保留真人面部、口型同步和手势，逐帧对齐，用的是 gemini-omni-flash 的 video-edit，失败时自动重试 seedance-2.0 的 reference-to-video。这里的关键词是保留：它不是在原视频上贴一层滤镜，而是重绘的同时锁住人脸和口型，这个约束比纯生成难得多。

C-roll 针对只有一张静态照片的情况，自拍或产品图都算。主体被抠成一张照片贴纸，README 强调它不会被重画，然后每个 beat 的海报围绕这张贴纸生成，走的是 nano-banana-2 的 edit 接口。旁白还可以克隆成照片里那个人的声音，用 bytedance/seed-audio-1.0。

三条路径共用同一份 beats.json 和同一套组装逻辑，这是这个项目结构上比较干净的地方。反过来说，C-roll 涉及真人照片和声音克隆，README 没有讨论授权、肖像权或数据留存政策，这部分需要使用者自己判断。

模型清单会漂移，所以它每次先去问一次

README 列了一张模型表，并标注为 verified on Atlas Cloud。关键帧用 google/nano-banana-2/text-to-image，非真人内容做动态用 google/gemini-omni-flash/image-to-video，真人或品牌内容换成 kwaivgi/kling-video-o3-pro/image-to-video，口播重制用 google/gemini-omni-flash/video-edit，照片锚定用 google/nano-banana-2/edit，旁白用 xai/tts-v1，真人音色克隆用 bytedance/seed-audio-1.0，音乐用 minimax/music-2.6，抠图用 youchuan/v8.1/remove-background。

真正值得注意的是紧随其后的一句话：模型 ID 会变，所以 skill 在运行前会先 GET https://api.atlascloud.ai/api/v1/models 拉一次实时列表。这是个务实的做法，把模型名漂移的风险从代码里挪到了运行时。但它也意味着这个 skill 强绑定 Atlas Cloud，换供应商不是改个配置项的事，而是要重写模型选择那一段。

同时，README 没有说明当实时列表里缺少某个模型时会发生什么，是报错、降级还是跳过。这是文档里一个明确的空白。

装起来要动的东西不多

安装方式有两种。从仓库装，把仓库克隆到 Claude Code 的 skills 目录：

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

或者下载打包好的 vox-director.skill，通过 Claude 的 skills 界面安装。Claude Code 会自动把它识别为 skill；其他 agent 走 AGENTS.md 再进 SKILL.md。

然后设置密钥，README 给的命令是 export ATLASCLOUD_API_KEY="sk-..."，key 在 atlascloud.ai 的控制台申请。

运行环境要求四项：一个能读工作流并执行脚本的编码 agent；Atlas Cloud 的 API key；本机的 ffmpeg 和 ffprobe，macOS 上 brew install ffmpeg；以及 Python 3 加 Pillow，pip install pillow，README 说明 Pillow 是给字幕和水印叠加用的。

用法是对话式的。README 给的例子是让 agent 做一条介绍墨西哥街头小吃的 Vox 风格拼贴视频，英语、16:9、15 秒，agent 会先起草 beat map 等你确认，再跑风格 bake-off 让你挑，然后依次生成关键帧、动态、人声、音乐，最后组装出 out/<project>/final.mp4。

这里有个细节值得注意：字幕和水印是 Pillow 在本地画的，不是模型生成的，所以这两样东西的排版可控，但也意味着中文标题的字体和换行要自己确认，README 没有涉及字体配置。

它在什么时候是错的工具

最明显的一条：如果你要的是稳定、可重复、可批量渲染的成片，这个项目不合适。它每一步都经过生成式模型，同一份 beats.json 跑两次，海报不会长得一样，这是扩散类模型的固有性质，不是配置能解决的问题。做品牌内容需要视觉一致性的团队要提前想清楚这一点。

第二条跟隐私有关。A-roll 要把口播视频送去重制，C-roll 要把真人照片送去生成、还可能把声音送去克隆。README 完全没有讨论数据如何被 Atlas Cloud 处理、保留多久、能不能删除。对涉及未公开产品、未成年人或客户素材的场合，这是必须先解决的问题，而不是跑起来之后再说。

第三条是依赖面。它同时依赖一个编码 agent、一个云 API、本机 ffmpeg 和 Python 环境，任何一环出问题流程都会在中间断掉。README 没有描述断点续跑或缓存机制，也没说已经生成好的关键帧能不能跳过重跑。对一条 60 秒的片子来说，中途重来一次的代价可能不小。

最后，README 里所有示例视频的时长都在 30 秒到 60 秒之间，看不出长视频或多语言混排的表现。如果你的目标是一次做十分钟的内容，这个项目没有给出任何依据。

跟 Remotion 这类代码化视频的区别在哪

把视频当代码来写，Remotion 是这条路线上被引用最多的方案：你用 React 组件描述每一帧，用 CSS 和 SVG 排版，渲染结果完全确定，同一份代码跑一百次出来一百个一样的文件。适合做数据驱动的批量内容，比如每周根据一份 JSON 生成一条固定版式的短片。

vox-director 走的是相反的方向。它不让你描述帧，而是让你描述意图，剩下的交给模型。拼贴海报、动态、旁白、配乐都是生成的，所以它能做出 Remotion 做不出来的东西：每一条片子的视觉都是新的，不依赖你预先准备好的素材库和版式。代价就是上面说的不可复现，以及对外部推理服务的强依赖。

选择其实很清楚。需要确定性、需要版本控制、需要 CI 里跑渲染，用 Remotion。需要快速试出几十种视觉方向、或者手上根本没有素材只有一句话题目，vox-director 这条路更省事。两者不冲突，甚至可以先用它出概念，再用代码化的方式把选定的方向固化下来。

维护成本与许可证

项目采用 MIT 许可证，这是最宽松的一类，商用、修改、再分发都可以，只需要保留版权声明和许可证文本。需要注意的边界在于：MIT 覆盖的是这个仓库里的代码和文档，不覆盖你通过 Atlas Cloud 调用的那些模型，也不覆盖生成出来的内容。模型的使用条款、生成内容的商用权利、以及声音克隆在具体司法辖区里的合法性，都是另一套规则，README 没有涉及，这里也不做法律判断。

维护成本主要不在这份 Python 代码上。真正的开销是模型 ID 漂移带来的适配工作，以及 Atlas Cloud 的计费。README 里没有任何价格信息，也不清楚一次 60 秒成片大概消耗多少额度，这部分只能自己跑一遍看账单。

版本方面，仓库没有发布任何 release，最近一次推送是 2026 年 8 月 11 日，默认分支是 main。也就是说，没有版本号可以锁，跟进上游只能跟 main。对打算把它放进生产流程的团队来说，这意味着要么自己 fork 一份固定下来，要么接受随时可能被上游改动影响。

另一个细节是文档的双语维护。SKILL.md 和 SKILL.zh.md 是同一份工作流的两个语言版本，README 也有中英两份。两份文档同步更新本身就是一项持续的维护工作，而仓库里没有任何机制保证它们不会分叉。

编辑结论

适合已经在用 Claude Code 或 Codex、手上有 Atlas Cloud API key、并且愿意在 beat map 和风格 bake-off 两个关口上花时间做判断的人。不适合想要一键出片、不接受人工审核环节、或者不愿把素材上传到第三方推理服务的人。动手前先确认三件事：你的 Atlas Cloud 账号能调用 nano-banana-2、gemini-omni-flash 和 xai/tts-v1 这几个模型；本机 ffmpeg 与 ffprobe 可用且 Python 3 装好了 Pillow；以及 C-roll 走 bytedance/seed-audio-1.0 做声音克隆时，你对把真人照片和声音交给外部服务的合规边界是否清楚。这三条里任何一条不成立，流水线都会在中间某一步停住。

官方来源

1. Alisa0808/vox-director on GitHub
2. Issues
3. License: MIT
4. README