Vox 拼贴动画 Skill 开源：一条口播、一张照片，怎么自动变成完整短片？

一条有旁白、有节奏、有统一视觉的拼贴动画，到底要做多少步？

先拆文稿，再画分镜；找照片、抠人物、做纸张纹理；接着加推拉、撕纸、胶带和半调网点；最后还要处理旁白、字幕、配乐与音画同步。以前，这是一条需要编导、设计和动效反复交接的生产线。

现在，一个叫 vox-director 的开源 Agent Skill，把这条链路装进了 Claude Code、Codex 等编码 Agent。你给它一个主题、一段口播视频或一张照片，它会先做内容规划，再生成拼贴关键帧、动画、旁白、配乐和字幕，最后通过本地 FFmpeg 合成视频。

它最值得看的地方并不是“像不像 Vox”，而是作者把一种视觉创作方法拆成了可执行、可检查、可替换模型的工程流程。

TL;DR

• vox-director 是开源的通用 Agent Skill，采用 MIT License，适用于 Claude Code、Codex 等能够读取 Skill 并执行脚本的 Agent。
• 它支持三种输入：口播视频转拼贴的 A-roll、从主题生成讲解片的 B-roll，以及一张照片进入拼贴世界的 C-roll。
• 视觉风格和视频运动被拆成两个阶段：先生成完整拼贴海报，再让海报运动；这是成片不容易“散掉”的关键。
• 原仓库当前默认且唯一实现的 Provider 是 Atlas Cloud。迁移到 Apito 时，需要增加 Provider 适配层，不能只替换环境变量。
• Apito 可作为多模型访问层，统一 Key、模型选择、调用记录和成本观察；具体图像、视频、语音模型及接口，以控制台实时可见信息和模型文档为准。

这不是一个滤镜，而是一条“从主题到成片”的流水线

很多 AI 视频工具解决的是某一个局部：有的生成图片，有的让图片动起来，有的负责配音。但真正制作一条讲解视频时，最麻烦的恰恰是把这些步骤接起来。

vox-director 用一个项目级的 beats.json 管理整条片子。每一个 beat 对应一个叙事节拍，里面可以记录文案、时长、画面描述、模型选择、风格和输出文件。后续脚本围绕这份数据依次工作：

1. 把主题或口播拆成节拍；
2. 选择一条叙事结构；
3. 用同一个节拍试做多套视觉风格；
4. 生成人物、产品或主题对应的拼贴关键帧；
5. 将关键帧变成短视频片段；
6. 生成旁白、配乐和字幕；
7. 用 FFmpeg 统一画幅、音量、时长并合成成片；
8. 检查身份一致性、字幕可读性和音画同步。

换句话说，模型只是流水线上的工位。真正把成片质量拉开的，是节拍表、风格锁定、输入输出规范和检查门槛。

beats.json 才是整条片子的控制台

如果只看最终画面，很容易把这个项目理解成“连续调用几个生图、生视频模型”。但它真正重要的中间产物是节拍表。一个可维护的 beat 不该只有一句提示词，至少要回答六个问题：这一段讲什么、持续多久、画面主体是谁、哪些元素不能改变、画面怎样运动，以及交付物保存在哪里。

下面是一份简化后的结构示意，它不是对原仓库字段的逐字复制，而是适合团队二次开发时使用的工程化写法：

{
  "project": "api-200-business-failure",
  "format": { "ratio": "16:9", "fps": 24 },
  "style_lock": "warm paper collage, black type, orange accent",
  "beats": [
    {
      "id": "beat-01",
      "narration": "API 返回 200，只能说明请求被接收。",
      "duration_sec": 3.2,
      "visual_goal": "接口响应卡片与失败业务流程形成反差",
      "immutable": ["响应码 200", "橙色状态灯"],
      "motion": "slow push-in, status light blinks once",
      "status": "keyframe_approved",
      "outputs": {
        "keyframe": "assets/keyframes/beat-01.png",
        "clip": "assets/clips/beat-01.mp4"
      }
    }
  ]
}

{
  "project": "api-200-business-failure",
  "format": { "ratio": "16:9", "fps": 24 },
  "style_lock": "warm paper collage, black type, orange accent",
  "beats": [
    {
      "id": "beat-01",
      "narration": "API 返回 200，只能说明请求被接收。",
      "duration_sec": 3.2,
      "visual_goal": "接口响应卡片与失败业务流程形成反差",
      "immutable": ["响应码 200", "橙色状态灯"],
      "motion": "slow push-in, status light blinks once",
      "status": "keyframe_approved",
      "outputs": {
        "keyframe": "assets/keyframes/beat-01.png",
        "clip": "assets/clips/beat-01.mp4"
      }
    }
  ]
}

这份数据有三个作用。第一，Agent 中断后可以从某个 beat 续跑，不必重新生成整条片子；第二，更换模型时只重做对应工位；第三，人工审核有明确对象，不需要在聊天记录里翻找“刚才确认的是哪一版”。

建议给每个 beat 设计状态流转：draft → style_approved → keyframe_approved → animated → audio_synced → passed。只有前一状态完成，才允许进入下一步。它会让流程慢几分钟，却能省掉大量无效的视频生成。

三条路线：A-roll、B-roll 和 C-roll 怎么选

A-roll：你已经录好了口播

A-roll 适合真人出镜、数字人口播或访谈片段。输入是一条带声音的口播视频，也可以附上原始文稿作为热词表和校对基准。

Skill 会先转录音频，并用词级时间戳把视频切成不超过模型限制的短段。随后，人物被保留为摄影质感的撕边贴纸，背景和道具才被改造成报纸、胶带、半调网点与剪纸元素。

这里的关键不是一句“改成拼贴风”，而是明确写下保护规则：

• 人脸、口型、视线和手势按原视频保留；
• 只重做人物之外的视觉世界；
• 背景元素不能遮住脸和手；
• 强调词出现的时间来自转录时间戳，而不是让视频模型猜节奏；
• 原始音轨单独保留，生成片段完成后再覆盖回去。

如果你要做知识口播、产品介绍或栏目包装，这是最接近“把已有视频升级成统一视觉”的路线。

B-roll：只有一个主题，也能从零生成

B-roll 的输入可以简单到一句话，例如：

做一条 30 秒的纸张拼贴讲解视频，解释为什么模型价格下降了，Agent 任务成本却不一定同步下降。

Agent 会先写脚本和节拍表，然后为每个节拍生成一张完整拼贴海报，再把海报转成短视频片段。旁白、音乐和字幕也由流水线继续生成。

这条路线最适合：

• 科普解释视频；
• 产品功能介绍；
• 品牌故事或时间线；
• 不需要真人出镜的社媒短片；
• 需要快速测试多个内容方向的团队。

C-roll：只有一张照片，也能让主体进入画面

C-roll 介于前两者之间。你不想重新录口播，也不希望画面完全由 AI 虚构，只想保留一个真实人物、头像或产品。

Skill 会把照片中的主体当成视觉锚点：人物或产品本身尽量不重绘，而是被剪成摄影贴纸；周围的版面、标签、纸片和背景根据每个节拍重新生成。如果配置了声音样本，还可以为照片主体生成对应旁白。

它适合产品广告、个人 IP 介绍、活动人物海报和“静态照片变讲解短片”等场景。

为什么拼贴视频最容易失败在“第一张图”

拼贴的视觉和运动必须分开处理。

第一阶段先把每个镜头做成一张能够独立成立的海报：它需要有明确主体、纸张层次、剪切边缘、颜色关系、留白和信息焦点。如果第一张图只是普通插画加几个胶带贴纸，后面再强的图生视频模型也救不回来。

第二阶段才给海报增加运动。适合拼贴的动作通常很克制：纸片漂移、轻微视差、局部推近、印章弹入、撕纸转场或停格节奏。动作越多，不一定越高级，反而容易让文字变形、人物漂移，甚至破坏平面设计感。

vox-director 先用同一个 beat 生成三到四套风格试片，让使用者先看图选方向，再把选中的风格应用到整条视频。这一步看似多花一次调用，实际上能避免生成十几个镜头后才发现方向不对。

安装前先检查这四件事

1. 查看仓库而不是只复制安装命令

第三方 Skill 本质上是一组提示词、脚本和执行规则。安装前至少检查：

• SKILL.md 和 AGENTS.md 会让 Agent 做什么；
• scripts/ 是否读取本地文件或执行外部命令；
• API Key 从哪个环境变量读取，会被发送到哪里；
• 输出目录是否可能覆盖已有项目；
• 仓库许可证是否允许你的使用方式。

2. 准备本地环境

原仓库公开文档列出的基础环境包括：

• Claude Code、Codex 或其他可执行脚本的编码 Agent；
• Python 3；
• Pillow，用于字幕和图像处理；
• FFmpeg 与 FFprobe，用于视频、音轨和字幕合成；
• 对应模型服务的 API 凭证。

可以先检查：

python --version
ffmpeg -version
ffprobe -version

python --version
ffmpeg -version
ffprobe -version

缺少 Pillow 时安装：

pip install pillow

pip install pillow

3. 安装 Skill

使用 Skills CLI：

npx skills add https://github.com/Alisa0808/vox-director --skill vox-director

npx skills add https://github.com/Alisa0808/vox-director --skill vox-director

也可以克隆到 Agent 的 Skill 目录。以 Claude Code 为例：

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

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

安装后不要立刻处理长视频。先让 Agent 阅读 SKILL.md、references/models-and-gotchas.md 和 Provider 实现，再用 5—10 秒素材跑通最小链路。

建议先把项目目录固定下来

自动化视频最怕文件名随对话变化。关键帧、视频片段、字幕和最终成片混在一个目录后，Agent 很容易读到旧文件，或者在重试时覆盖已经确认的版本。可以从下面这套结构开始：

project/
├─ brief.md                    # 目标、受众、平台、时长和禁用项
├─ beats.json                  # 唯一的节拍与状态来源
├─ config/
│  ├─ style-guide.md           # 色彩、字体、纸张、运动规则
│  └─ model-map.json           # 逻辑工位到真实模型 ID 的映射
├─ sources/                    # 原视频、照片、脚本和授权材料
├─ assets/
│  ├─ transcripts/             # 转录文本和词级时间戳
│  ├─ keyframes/               # 审核前后的关键帧
│  ├─ clips/                   # 单个 beat 的视频片段
│  ├─ audio/                   # 原音轨、旁白和音乐
│  └─ subtitles/               # SRT、ASS 等字幕文件
├─ renders/                    # 预览版与最终版
└─ logs/                       # 请求、耗时、费用和错误记录

project/
├─ brief.md                    # 目标、受众、平台、时长和禁用项
├─ beats.json                  # 唯一的节拍与状态来源
├─ config/
│  ├─ style-guide.md           # 色彩、字体、纸张、运动规则
│  └─ model-map.json           # 逻辑工位到真实模型 ID 的映射
├─ sources/                    # 原视频、照片、脚本和授权材料
├─ assets/
│  ├─ transcripts/             # 转录文本和词级时间戳
│  ├─ keyframes/               # 审核前后的关键帧
│  ├─ clips/                   # 单个 beat 的视频片段
│  ├─ audio/                   # 原音轨、旁白和音乐
│  └─ subtitles/               # SRT、ASS 等字幕文件
├─ renders/                    # 预览版与最终版
└─ logs/                       # 请求、耗时、费用和错误记录

原始素材放进 sources/ 后尽量只读；每次重试生成新版本号，例如 beat-03-keyframe-v02.png，不要覆盖 v01。确认版本再由 beats.json 指向它。这样既方便回滚，也能找出究竟是哪一次模型调用改善或破坏了结果。

4. 先确认你跑的是原版还是适配版

原仓库当前的 scripts/provider.py 默认注册 atlas_cloud，相关脚本会读取 ATLASCLOUD_API_KEY，并调用其专用任务提交、查询和模型目录接口。

因此，如果你准备使用 Apito，需要先增加 Apito Provider，或者改用已经完成兼容性验证的适配分支。仅执行下面这种机械替换并不够：

ATLASCLOUD_API_KEY → APITO_API_KEY

ATLASCLOUD_API_KEY → APITO_API_KEY

Key 名称变了，不代表请求地址、鉴权方式、任务提交格式、异步轮询和结果字段也自动兼容。

Apito 应该接在哪一层

Apito（ClaudeAPI）是独立第三方多模型 API 接入平台。它更适合放在“模型访问层”，而不是替代 vox-director 的创作逻辑。

整条关系可以理解为：

选题/口播/照片
      ↓
vox-director：脚本、节拍、风格、质检规则
      ↓
Apito Provider：Key、Base URL、模型映射、请求与结果转换
      ↓
文本 / 图像 / 视频 / 语音模型
      ↓
本地 FFmpeg：合成、字幕、原音轨、最终导出

选题/口播/照片
      ↓
vox-director：脚本、节拍、风格、质检规则
      ↓
Apito Provider：Key、Base URL、模型映射、请求与结果转换
      ↓
文本 / 图像 / 视频 / 语音模型
      ↓
本地 FFmpeg：合成、字幕、原音轨、最终导出

通过这种分层，创作流程不需要知道每个模型服务的底层差异；模型迁移也集中在 Provider 和模型映射表里完成。

获取 Apito API Key

登录 Apito，在控制台创建 API Key。示例中只使用占位符，不要把真实 Key 写进仓库或截图：

export APITO_API_KEY="sk-你的Key"
export APITO_BASE_URL="https://apito.ai"

export APITO_API_KEY="sk-你的Key"
export APITO_BASE_URL="https://apito.ai"

Windows PowerShell：

$env:APITO_API_KEY = "sk-你的Key"
$env:APITO_BASE_URL = "https://apito.ai"

$env:APITO_API_KEY = "sk-你的Key"
$env:APITO_BASE_URL = "https://apito.ai"

先用文本请求验证 Key 和 Base URL

在修改视频流水线前，先做一个最小请求，确认凭证、模型 ID 和请求地址可用：

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("APITO_BASE_URL", "https://apito.ai"),
    api_key=os.environ["APITO_API_KEY"],
)

response = client.chat.completions.create(
    model="控制台当前可见的模型ID",
    messages=[
        {
            "role": "user",
            "content": "把‘API 返回成功不等于业务成功’拆成 5 个视频节拍。",
        }
    ],
)

print(response.choices[0].message.content)

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("APITO_BASE_URL", "https://apito.ai"),
    api_key=os.environ["APITO_API_KEY"],
)

response = client.chat.completions.create(
    model="控制台当前可见的模型ID",
    messages=[
        {
            "role": "user",
            "content": "把‘API 返回成功不等于业务成功’拆成 5 个视频节拍。",
        }
    ],
)

print(response.choices[0].message.content)

模型名称、接口能力和价格以控制台实时信息为准，不要把社区文章里的内部名称直接写入生产配置。

Provider 至少要适配六类行为

如果要让原版 Skill 完整迁移到 Apito，Provider 需要处理：

1. 从环境变量安全读取凭证；
2. 把 Skill 中的逻辑模型名称映射为控制台真实模型 ID；
3. 按不同模型能力构造文本、图像、视频和语音请求；
4. 处理同步返回与异步任务轮询；
5. 将各种返回结果统一成 Skill 认识的文件或 URL；
6. 对超时、限流、内容拒绝和任务失败进行分类，而不是无限重试。

原仓库的 Provider 接口已经提供了改造入口，但截至本文核验时，公开主分支仍只实现了 Atlas Cloud。Apito 接入应以经过测试的适配器为准，不建议直接在生产项目里边改边跑。

不要把“提交成功”当成“生成成功”

视频和部分图像接口通常是异步任务：第一次请求只返回任务 ID，真正的文件要经过排队、运行和结果查询。Provider 至少要区分下面这些状态：

重试建议同时满足三个条件：错误可恢复、次数没有超过上限、该 beat 尚未产生可用文件。网络超时和临时限流可以退避重试；鉴权失败、模型 ID 错误、参数不支持和内容拒绝，应该立刻停止并暴露给操作者。

可以为每次生成建立一条最小调用记录：

{
  "beat_id": "beat-01",
  "stage": "image_to_video",
  "provider": "apito-adapter",
  "model_id": "控制台实际模型ID",
  "request_id": "req_xxx",
  "attempt": 1,
  "started_at": "2026-08-26T10:30:00+08:00",
  "latency_ms": 42800,
  "status": "succeeded",
  "input_units": null,
  "output_units": null,
  "estimated_cost": null,
  "output": "assets/clips/beat-01-v01.mp4"
}

{
  "beat_id": "beat-01",
  "stage": "image_to_video",
  "provider": "apito-adapter",
  "model_id": "控制台实际模型ID",
  "request_id": "req_xxx",
  "attempt": 1,
  "started_at": "2026-08-26T10:30:00+08:00",
  "latency_ms": 42800,
  "status": "succeeded",
  "input_units": null,
  "output_units": null,
  "estimated_cost": null,
  "output": "assets/clips/beat-01-v01.mp4"
}

不能从接口稳定拿到费用时，就保留 null，不要用想象中的单价伪造“精确成本”。但请求次数、模型 ID、耗时、失败率和产物路径必须记录，这些信息已经足够帮助团队定位最烧钱、最不稳定的工位。

怎样选择模型，而不是迷信一张固定清单

这条流水线至少包含五类任务：脚本规划、语音转录、图片生成或编辑、视频生成或编辑、旁白与音乐。没有一个模型在所有环节都占优。

建议在项目里维护一张任务映射表：

Apito 的价值在于把模型访问、切换和调用记录集中到一层。某个环节效果不理想时，可以在控制台实际支持范围内更换对应模型，而不必重写整个内容流程。但切换后仍要重新跑该工位的验收样例，不能默认不同模型的参数和输出完全一致。

第一次运行，建议只做 10 秒

第一次测试可以把任务压缩到最小：

请使用 vox-director 制作一条 10 秒、16:9 的纸张拼贴讲解片。
主题：为什么 API 返回 200，业务仍可能失败。
先只输出 beats.json 和三套风格试片，不要继续生成视频。
我确认节拍与风格后，再生成关键帧和动画。
所有模型调用使用项目中已配置并验证过的 Apito Provider；
模型 ID 以当前控制台可见列表为准。

请使用 vox-director 制作一条 10 秒、16:9 的纸张拼贴讲解片。
主题：为什么 API 返回 200，业务仍可能失败。
先只输出 beats.json 和三套风格试片，不要继续生成视频。
我确认节拍与风格后，再生成关键帧和动画。
所有模型调用使用项目中已配置并验证过的 Apito Provider；
模型 ID 以当前控制台可见列表为准。

这个提示词故意设置了两个确认点：先看节拍，再选风格。不要一开始就让 Agent 连续生成完整成片，否则一个错误方向会消耗后续所有调用。

建议按下面顺序验收：

1. beats.json 是否符合主题和时长；
2. 三套风格试片是否真的有明显差异；
3. 关键帧的主体、颜色和纸张质感是否连续；
4. 视频片段有没有文字变形、人物漂移和错误遮挡；
5. 旁白时间能否覆盖镜头；
6. 单个 beat 失败后能否从断点恢复；
7. 日志能否追溯到模型、请求和对应产物；
8. FFmpeg 导出的文件能否在手机与浏览器正常播放。

从 10 秒样片扩展到完整成片

样片通过后，也不要立刻一口气生成全部内容。更稳妥的做法是分四个批次推进：

低码率预览很重要。第一次合成只需要让团队判断内容和节奏，没有必要反复输出高码率文件。所有修改确认后，再导出平台所需的最终分辨率、码率和封装格式。

发布前最后检查一次

• **内容：**事实、数字、专有名词和引用来源已经复核；
• **画面：**人物没有换脸，产品结构和 Logo 没有变形，文字没有乱码；
• **声音：**人声清楚，音乐不盖对白，开头结尾没有爆音；
• **字幕：**断句自然，没有超出手机安全区，与旁白时间一致；
• **技术：**分辨率、帧率、编码、时长和文件大小符合平台要求；
• **权限：**照片、字体、音乐、声音样本和模型输出满足实际使用场景；
• **可追溯：**最终视频能对应到 beats、模型调用记录和确认过的素材版本。

6. 原始音轨、字幕与配乐是否正确混合；
7. 失败任务是否停止计入后续步骤并留下日志。

五个常见坑，原文里最有价值的其实是这些

1. 长口播必须切段

不同视频模型有单次时长和文件大小限制。长视频应沿句子边界或自然停顿切分，逐段生成后再拼接。不要从一个词中间硬切，否则嘴型和音频都难处理。

2. 生成视频通常不保留原音轨

A-roll 完成后，要把原片音频重新混入生成画面。项目必须把视频和音频当成两条独立轨道管理。

3. 中文标题不要完全交给生图模型

短英文印章相对容易稳定，中文标题仍可能出现错字、乱码和笔画问题。更稳妥的方法是让模型生成不含正文文字的拼贴底图，中文标题和字幕通过 HTML、Pillow 或剪辑软件后期排版。

4. 人物保护规则不能省

“保持人物一致”太宽泛。需要写清身份、脸部、嘴型、视线、手势、服装和构图分别能不能改。C-roll 产品图还要锁定标签、包装比例和关键文字。

5. 自动重试必须有上限

内容拒绝、参数错误和临时限流不是同一种失败。参数错误应该立即停止并修正，临时错误才适合退避重试。每个阶段都应设置最大次数、最大等待时间和预算上限。

这类 Skill 真正改变的是什么

vox-director 没有消灭编导、设计和剪辑判断，而是把他们反复执行的步骤写成了一份 Agent 可以遵循的生产规范。

以前，团队依赖某个动效师“知道该怎么做”；现在，叙事节拍、视觉风格、模型分工、确认节点和验收条件可以沉淀在 Skill、配置文件与脚本里。换一个人或换一个模型，工作流仍能继续复用。

这也是 Agent Skill 比一段提示词更有价值的原因：提示词描述一次结果，Skill 规定一套稳定生产结果的方法。

FAQ

vox-director 可以直接安装在 Codex 里吗？

可以。仓库提供了 AGENTS.md 作为非 Claude Agent 的入口，能够读取工作流并运行脚本的编码 Agent 都可以使用。不过不同 Agent 的 Skill 目录、权限确认和环境变量配置不同，安装后应先让它解释将要执行的脚本，再批准运行。

换成 Apito API Key 后，原仓库能直接运行吗？

不能只换 Key。公开主分支当前只实现了 Atlas Cloud Provider。迁移到 Apito 需要增加 Provider 适配层，处理请求地址、鉴权、模型 ID、异步任务和返回字段。可以先用 Apito 完成脚本规划等兼容请求，再逐项适配图像、视频和语音环节。

Apito 里应该选择哪个模型？

不要根据文章写死模型。先查看控制台当前真实可见的模型和能力，再分别为文本、转录、图像、视频与语音建立小型验收样例。价格、接口和可用状态也以控制台为准。

为什么不直接一次生成一分钟视频？

因为长任务会放大方向错误、人物漂移、音画不同步和调用失败的成本。先用 5—10 秒跑通节拍、风格、关键帧和合成，再逐步增加长度更稳妥。

拼贴动画可以商用吗？

仓库采用 MIT License，但商用时仍需分别检查使用的模型条款、输入素材授权、字体、音乐、声音克隆和最终内容中的第三方商标。开源代码许可不等于所有素材自动获得商业授权。

总结

如果你只是想试一次拼贴效果，复制提示词、做一张海报就够了。如果你希望每周稳定生产多条视频，真正需要的是 vox-director 这类可检查、可复用的工作流。

开始时别急着追求“一句话生成一分钟成片”。先安装 Skill，审核脚本权限，用 10 秒测试片确认节拍和视觉，再逐步接入模型、旁白、音乐与自动合成。

需要统一管理模型访问时，可以登录 Apito 创建 API Key，并以控制台当前模型列表和接口文档完成 Provider 适配。更换模型只应影响模型访问层，不应推倒已经验证过的创作流程。

参考资料

• Alisa0808/vox-director GitHub 仓库
• vox-director 中文 README
• vox-director 中文 Skill 说明
• Apito

说明：本文基于 2026 年 8 月 26 日可见的公开仓库核验。第三方项目、模型列表与接口可能继续更新，实际使用前请重新检查仓库说明和 Apito 控制台。