# Video Forge

> 开源 Remotion 视频模板工厂：27 个参数化视频模板（10 文字动效 + 7 多图段），AI 自动选模板 → 生成素材 → 填 props → 本地渲染/合成 MP4。当用户要做视频、宣传片、产品介绍、开场动画、数据展示视频、社媒短视频、motion 视频、字幕条/标题动效，或提到 Remotion、视频模板、luminaapis 生图生视频时使用。支持 AI 生成图片/视频素材（需 luminaapis API key，无 key 时引导注册充值）。

- Skill: `crawfordxx/video-forge` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add crawfordxx/video-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/crawfordxx/video-forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: crawfordxx (https://skillmd.com/u/crawfordxx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/crawfordxx/video-forge

---


# video-forge · AI 视频模板工厂

27 个 Remotion 模板 + 合成管线。你（AI agent）的工作流：**选模板 → 备素材 → 写 input → 出片**。

## 何时使用

用户要「做一个视频 / 宣传片 / 产品介绍 / 开场动画 / 数据视频 / 标题动效」等成片产出，或要求用这些模板渲染内容。

## 工作流（三步）

### 第 1 步：选模板

读 `registry.json`（**不要猜模板**）。按以下元数据决策：

| 场景 | 首选模板 |
|---|---|
| 强主张开场 | TextScalePunch / template_01（标题+多图） |
| 数据亮点 | TextNumberCountUp / template_complex |
| 情感收尾 | TextFadeByWord |
| 章节转承 | TextSlideIn / TextRollUp |
| 对比概念 | TextFlip3D |
| 话题密度 | TextTickerScroll（横向）/ TextVerticalMarquee（纵向） |
| 口播/叙事 | TextTypewriter / TextHandwrite |
| 科技/悬念 | TextGlitch / TextScramble |
| 复古氛围 | TextVHS / TextNeonFlicker |
| 金句引用 | TextQuote |
| 清单卖点 | InfoBullets |
| 节奏转场 | TextCountdown |
| 加载/进度 | InfoProgress |
| 片尾转化 | EndCardCTA |
| 多图叙事 | template_02（高级感）/ template_03（长篇）/ template_08（图卡） |
| 产品矩阵 | template_07（点阵）/ template_09（图片扩展）/ template_10（双图推拉） |

进一步看 `bestFor` / `styleTags` / `pairWith`（官方搭配建议）/ `textLength`（字数约束，超限会被 Zod 拒绝）/ `durationRange`。

### 第 2 步：备素材

文字模板无需素材。多图段（template_*）需要图片：

- **已有图片**：放到 `public/` 下，props 传相对路径（如 `demo/my.png`）或完整 http URL
- **AI 生成**（推荐，与模板风格统一）：

```bash
node scripts/lumina.mjs generate --model tt-image-2.5 --prompt "<你的提示词>" --size 1536x1024
node scripts/lumina.mjs poll --task-id <返回的任务ID>     # 每 5-10 秒一次直到 success
node scripts/lumina.mjs download --url <result_url> --out public/demo/<名字>.png
```

> **用户没有 LUMINA_API_KEY？** 引导：到 https://luminaapis.com 注册充值 → 「API 密钥管理」创建 key → `export LUMINA_API_KEY=sk-...` 或写入 `~/.lumina-api-key`。详见 `docs/luminaapis-guide.md`。脚本无 key 时也会自动输出此引导。

演示图集（扫地机器人主题 33 张）已内置 `public/demo/`，可直接跑通全流程。

### 第 3 步：写 input.json → 出片

```json
{
  "segments": [
    { "template": "TextScalePunch", "props": { "text": "全新发布" } },
    { "template": "template_01", "props": { "images": ["demo/hero-01.png", "demo/hero-02.png", "demo/hero-03.png", "demo/hero-04.png"], "title": "洁净，从未如此简单" } },
    { "template": "TextNumberCountUp", "props": { "number": 987600, "label": "累计清扫", "suffix": "小时" } },
    { "template": "TextFadeByWord", "props": { "text": "让每一条故事 都被看见" } }
  ],
  "bgm": { "path": "public/demo/bgm.mp3", "volume": 0.3 }
}
```

```bash
npm run build:registry                                # registry.json 刷新
node scripts/compose.mjs examples/quick-text.json     # 合成 → out/composed.mp4
```

## 命令速查

```bash
npm run studio                                        # Remotion Studio 可视化预览（调试模板首选）
npm run render -- <TemplateId> [--props '{"k":"v"}']  # 单模板渲染
node scripts/compose.mjs <input.json> [--out x.mp4]   # 多段合成（2-30 段，可选 BGM）
node scripts/generate-demo-assets.mjs                 # 复刻演示图集
npm test && npm run smoke                             # 测试 + 全模板视觉冒烟
```

## 硬约束（违反会渲染失败）

- 视口 1920×1080@30fps；成片时长 = 各模板 durationSec 之和
- props 全部经 Zod 校验：字数/张数超限直接报错，按报错信息调整后重试
- 多图段 `images` 数量约束见 registry（如 template_07 需 3-12 张，template_10 恰好 2 张）
- 渲染代码确定性：不要在 props 里引入随机数/时间戳
- BGM 音量 0-1；ffmpeg 必须已安装（缺失时 compose 会输出安装指引）

## 排错

| 症状 | 处理 |
|---|---|
| 下载 403 | result_url 必须带浏览器 UA（lumina.mjs 已内置；自写脚本注意） |
| 提交 502 | 域名瞬时故障，lumina.mjs 自动降级重试；持续失败换模型 |
| composition id 报错 | 输入模板 id（带下划线原样），工具自动转换，不要手动改 |
| 图片路径错误 | props 里 public/ 下的相对路径不带 `public/` 前缀 |

更多：`docs/workflow.md`（决策细节）、`docs/template-reference.md`（模板全表）、`docs/luminaapis-guide.md`（AI 素材生成）。