Vox Director

将一行主题文字转化为完成的 Vox 风格纸艺拼贴视频：一种大胆、有力、配有旁白的解释性广告视频，其中每一“拍”（beat）都是一张动态呈现的撕纸拼贴海报，辅以配音、配乐与字幕。运行依赖于 一个 Atlas Cloud API 密钥 + 本地 ffmpeg。

视觉风格源自 Vox 解释类视频及 Stav Zilber / rom1trs 等创作者所推广的现代编辑式纸艺拼贴：手工剪裁的纸片、毛边撕口、胶带粘贴、半调网点、旧报纸剪报、每拍使用高饱和纯色、大幅剪贴式标题文字。

核心理念（请先阅读）

Vox 拼贴外观与拼贴动态是 两个独立步骤：

1. 外观诞生于图像生成阶段（IMAGE step）。 每一拍对应一张由文生图模型生成的完整拼贴 海报。所有拼贴基因（撕纸边缘、剪裁元素、半调网点、高饱和色块、标题文字）均内生于该图像中。若图像本身缺乏丰富拼贴质感，则后续任何环节都无法补救。
2. 动态效果后置添加。 默认由 AI 视频模型对整张海报进行动画化（即“活化海报”路径——简单、全自动）。如需实现富有戏剧张力的 逐件组装 效果，则需将海报切分为多个组件，并由本地关键帧引擎驱动（进阶路径）。

一切成败系于提示词（prompt）。在撰写任何图像或视频提示词之前，请务必通读 references/prompt-guide.md —— 其中提供了精确的提示词结构，这是区分“真正 Vox 风格拼贴”与“会动的 PowerPoint”的决定性因素。

前置条件（请逐一检查，不可跳过）

• echo "${ATLASCLOUD_API_KEY:+set}" — 若输出为空，请提示用户设置环境变量（获取地址：https://www.atlascloud.ai/console/api-keys），并中止流程。
• command -v ffmpeg ffprobe — 组装阶段必需（macOS 用户可执行 brew install ffmpeg）。
• python3 -c "import PIL" — 需 Pillow 库支持字幕与水印叠加。

标准工作流（主题 → 成片）

这是默认且自动化程度最高的路径。每个阶段均由单个脚本驱动，全部围绕项目目录 out// 下的唯一 beats.json 文件展开。

1. 主题 → 分拍映射（beat map）。 首先 通读 references/beat-layer.md（故事层文档），为当前主题选择合适的叙事 arc（例如：历史类用 timeline，广告类用 pas/bab，说明类用 how_it_works，转型类用 man_in_hole …）。随后按所选结构编写 out//beats.json：其中 第 1 拍标题必须是 ≤3 秒的强钩子（hook）；总拍数依时长而定（30 秒→6–8 拍，60 秒→10–12 拍）；每拍拆分为 2 个镜头（广角+特写），且相邻拍之间的 每镜头 camera_move 必须变化（严禁重复；收尾镜头固定为 static），同时确保 丰富的 element_motion（见第 4 步）。每拍字段包括：narration、title_cn/title_en、scene、bg、feel、hook。此初稿是 唯一强制性的审批关卡 —— 务必先向用户展示分拍映射，确认无误后再进入生成阶段。示例见 examples/ 目录。

2. 选定视觉风格（混合式 —— 此步须在关键帧生成前完成）。 切勿为所有主题复用同一套视觉规范。请重读 references/prompt-guide.md（§5 主题预设），从中挑选 3–4 个契合主题时代背景/文化语境/情绪基调的 主题预设（styles.THEME_PRESETS：如 american-retro、swiss-modern、punk-zine、soviet-constructivist、wpa-propaganda、70s-groovy、chinese-ink、atomic-age）；若无合适预设，则可按提示词指南中的维度（媒介/时代/配色/类型/表面处理）自由组合，构建 自定义主题。风格匹配依据是主题本身，而非语言（例如一部讲述中国历史的英文影片，其视觉应体现中国风格）。一个主题预设即打包了完整的 LOOK 层（风格范式 + 色彩 + 类型 + 表面处理 + 情绪 + 运动逻辑）。执行风格比选（bake-off），由用户凭眼力择优 —— AI 提供选项，素材库保障下限质量，最终决策权在人。将选定名称设为 "theme" 字段：python3 scripts/style_bakeoff.py out/ american-retro,swiss-modern,punk-zine,atomic-age。并将所选名称写入 beats.json 的 "collage_style" 字段（keyframes.py 将读取该字段）。

3. 关键帧（拼贴外观）。 python3 scripts/keyframes.py out/ 使用 google/nano-banana-2/text-to-image 为每拍/每镜头生成一张拼贴海报，标题文字已内嵌于图像中。提示词须严格遵循 references/prompt-guide.md 中的五段式结构。在启动动画前，请逐一验证每张海报是否呈现真实的多层拼贴质感 —— 此处重试成本低廉（$0.08），远低于为低质图像支付高昂动画费用。

4. 动态效果。 python3 scripts/clips.py out/ 使用 google/gemini-omni-flash/image-to-video 为每张海报生成动画。该过程包含两个正交控制轴（详见 references/beat-layer.md §3，已在本技术栈上实测）： • camera_move — 每镜头仅允许一个运镜动作。安全/默认选项：{static, push_in, pull_out, pan, tilt, parallax}。大胆/实验性 选项：{orbit, dolly_zoom, roll, whip} —— 可用但非禁用；此类运镜可能扭曲平面艺术，故建议搭配 constraints: loose 并做好重试准备。任意自定义运镜描述亦可直通。 • element_motion — 能量所在；AI 将为每拍独立生成贴合场景的运动描述（非模板套用）。务必做到 RICH（多个元素同步运动）—— 勇于尝试。例如，在关键拍中，让一个 主角元素横穿画面（纸鸟/纸飞机/硬币）是极佳的 偶发性冲击点，但 切忌每镜皆用（若每帧都飞出一个元素，将沦为套路化表达）。 motion_style = 振幅等级：calm | punchy | max（主题预设已设定默认值）。constraints = strict（默认：缺陷防护开启 —— 严格保持 2D 平面、单向运动、禁止形变；最适合文字密集型说明类内容）或 loose（允许模型探索 3D 或大胆运镜；失败时需重试）。仅在含标题的镜头中，标题文字受硬性保护（不含标题的特写镜头可自由发挥）。对于 真实人物 / 品牌标识，Omni 与 Seedance 模型将拒绝生成 —— 此时请设置 "video_model": "kwaivgi/kling-video-o3-pro/image-to-video"。

5. 配音 + 配乐。 python3 scripts/audio.py out/ 通过 xai/tts-v1 提供统一旁白（支持多语言，指定 voice_id） + minimax/music-2.6 提供纯音乐 BGM。（除非已锁定说话人，否则 切勿 对普通旁白使用 seed-audio —— 详见常见陷阱说明。）

6. 合成成片。 python3 scripts/assemble.py out/ 使用 ffmpeg 完成音画归一化与拼接、将压低音量的旁白叠于背景音乐之上、按拍插入精准计时字幕、添加水印。最终输出 out//final.mp4。

7. 校验。 MP4 文件无法直接阅读 —— 可提取帧为 JPG 进行目视检查：ffmpeg -ss -i final.mp4 -vf "scale=640:-1,format=yuvj420p" -frames:v 1 f.jpg

节奏控制 — 单镜头时长建议

常见错误是每拍仅用一个长镜头。尤其在 9:16 竖版社交视频中，10 秒静止镜头极易被感知为“冷场”。建议每 约 4–6 秒切换一次镜头：

• 单镜头时长控制在 3–6 秒；绝对避免单镜头超过 ~7 秒 —— 超出此限时长，AI 动态将无处施展，画面易显呆滞。
• 每拍旁白时长约 8–10 秒，因此每拍应分配 2 个镜头（一个含标题的 广角 建立镜头 + 一个不含标题的 特写 切入镜头）。旁白全程连续播放，画面则在句子中途切换。这是提升节奏感最关键的一步。
• 因此，一部约 60 秒的影片通常为 约 6 拍 × 2 镜头 × 约 5 秒 = 12 个镜头，而非 6 × 10 秒。
• 复用广角关键帧作为镜头 a；为镜头 b 单独生成更紧凑的细节场景。由于 keyframes.py 会跳过已有 keyframe_url 的镜头，因此只需新增 b 镜头并重新运行脚本，即可仅生成新镜头图像。

在每拍中添加 shots 数组（参见 schema）。为每个镜头单独设定简短的 scene 与 motion 描述；仅在广角镜头中设置 "title": true，确保每拍标题仅显示一次。

beats.json 结构定义

{
  "project": "my-film", "topic": "...", "language": "en",
  "aspect": "9:16",                       // 16:9 | 9:16 | 1:1 | 3:4
  "style": "collage",
  "provider": "atlas_cloud",              // 媒体后端 — 默认值；可插拔（scripts/provider.py）
  "theme": "american-retro",              // THEME_PRESET（styles.THEME_PRESETS）— LOOK 层
  "arc": "timeline",                      // 叙事弧线（beat-layer.md）— STORY 骨架
  "video_model": "google/gemini-omni-flash/image-to-video",  // 含真实人物时改用 Kling
  "motion_style": "punchy",               // 振幅：calm | punchy | max（主题预设提供默认值）
  "constraints": "strict",                // strict = 开启缺陷防护 | loose = 允许 AI 探索 + 重试
  "voice": {"voice_id": "leo", "language": "en", "speed": 1.0},
  "music": "epic cinematic orchestral, instrumental, no vocals",
  "mix": {"music": 0.6, "voice": 1.25},   // 音频平衡 — 可选；此处为默认值（BGM 在 VO 下方压低）
  "watermark": "Made with Atlas Cloud",
  "beats": [
    {
      "id": 1, "title_cn": "", "title_en": "BEFORE MONEY",
      "bg": "earthy clay tan", "feel": "ancient, humble", "hook": "surprising_stat",
      "narration": "For most of history, there was no money...",
      "shots": [
        // shot_size: EST_WIDE|WIDE|MEDIUM|CLOSE|DETAIL ; camera_move: static|push_in|
        // pull_out|pan|tilt|parallax（仅限平面安全运镜）— 相邻拍之间必须变化，收尾镜头固定为 static
        {"id": "a", "dur": 5, "title": true,  "shot_size": "WIDE", "camera_move": "push_in",
         "scene": "...wide establishing collage...",
         "element_motion": "traders gesture, goat bobs, a paper bird flaps across the frame, coins scatter"},
        {"id": "b", "dur": 5, "title": false, "shot_size": "CLOSE", "camera_move": "parallax",
         "scene": "...close cut-in detail...",
         "element_motion": "the exchanged goods slide together, halftone pulses"}
      ]
    }
  ]
}

theme+arc 定义两大核心层级；每镜头的 element_motion 是能量来源（务必做到丰富 —— 见上文说明）。motion/collage_style/era 字段仍保留以兼容旧配置。

模型选型（务必验证 ID 是否有效）

模型 ID 会更新 —— 请首先获取实时列表：GET https://api.atlascloud.ai/api/v1/models（无需鉴权；仅保留 display_console: true 的条目）。当前可用的默认模型如下：

详见 references/models-and-gotchas.md，其中详述了全部模型选型逻辑，以及所有 API / ffmpeg 常见陷阱（认证 Header、curl 下载、无 libass 字幕支持、内容拦截等）。调试任何失败前，请务必先查阅此文 —— 大多数问题在此已有明确记录与解决方案。

后端系统支持插拔式扩展。 所有 API 调用均经由统一 provider（scripts/provider.py）路由；Atlas Cloud 是当前唯一且默认的后端。未来新增其他后端时，只需在 beats.json 中设置 "provider" 字段即可切换，各阶段脚本本身无需修改。scripts/provider.py 中的 run_jobs() 方法还内置了对停滞或失败任务的 自动重提交机制。

进阶功能：元素级运动拼贴

标准路径对 整张 海报进行动画化（效果出色、全自动、“活化海报”）。若需实现戏剧性的 元素飞入并组装 式拼贴动画（类似 cr7v2），或希望以完全可控、零内容过滤的方式为 真实人物 添加动画，则需将每张海报切分为独立元素，并由本地关键帧引擎驱动（无需调用视频模型）。

请参阅 references/local-engine.md。简而言之：通过 extract_elements.py（裁剪 + 去背 + 残留/擦除清理）→ motion.py（图层管理 + 关键帧，支持 fly_in/slap/drop/pop_settle 缓动、程序化彩纸/星爆效果、摄像机缩放/抖动/甩镜、逐帧渲染）。各元素将飞回其 原始位置，背景为模糊占位图，从而令最终组装画面精准还原原海报。

版本说明

• 自动版（本技能）：输入主题，输出成片，全流程依托 Atlas Cloud。
• 手动提示词包版：若用户未接入 Atlas Cloud，可仅输出分拍映射 + 每拍图像提示词 + 每镜头运动提示词 + 旁白脚本，供其粘贴至任意生成器中使用。创意引擎（即提示词体系）完全一致。