---
name: hilo-promo
display-name-zh: AI推广视频
description: |
  AI视频APP推广创作助手，专用于制作竖版（9:16）社交媒体推广短视频。
  基于「图片模板」，自动完成角色洗图、换脸写真生成、口播TTS、
  数字人口型同步、多段合成，输出 1080×1920 竖版推广视频及可选 4:5 裁切版。
  触发词：模板视频、template video、推广视频、promo video、推广模板、
  make a promo video、social media ad、换脸写真、图片模板推广。
version: 1.2.1
summary-cn: 用图片模板生成竖版推广短视频
summary-en: Photo templates to vertical promo video
tags: [Video, Marketing, Promo, AI-Template]
tags-cn: [视频, 营销, 推广, AI模板]
exported-by: MiniMax-hub
---

# AI Video Promo Creator

> 基于图片模板，输出竖版（1080×1920）推广教程视频。流程：角色洗图 → 换脸写真 → 口播 TTS → 数字人 PiP → 教程段 → 拼接合成。

---

## 全局约定

| 约定 | 规则 |
|------|------|
| 工作目录 | `./{project_name}/`，从需求自动提取 |
| 阶段推进 | 每阶段完成后展示结果，用 `question` 确认再推进 |
| 口播语言 | 默认英文，可由用户指定 |
| 生图 prompt | 始终英文 |

---

## 阶段一：需求解析

收集以下信息，缺失项向用户提问：

| 信息项 | 说明 |
|--------|------|
| 角色参考图 | 图片路径或文字外貌描述 |
| 模板图来源 | 写真模板图片路径或 URL |
| 口播脚本 | 英文文案；无则阶段四自动生成 |
| 尾板视频 | 默认 `{skill_root}/assets/endcard_en.mp4` |

**共享素材预检**：进入阶段二前检查 `{skill_root}/assets/` 下列文件，缺失则 `curl` 下载：

| 文件 | CDN URL |
|------|---------|
| `endcard_en.mp4` | `https://cdn.hailuoai.com/pre/2026-04-24-14/video/1777012954453480092-1777012954413.mp4` |
| `tut_001.mp4` | `https://cdn.hailuoai.com/pre/2026-04-24-14/video/1777013069159453139-1777013069157.mp4` |

**产出**：`./{project_name}/brief.md`

---

## 阶段二：角色形象生成（洗图）

1. **有参考图**：`read_media` 提取外貌特征（英文 prompt 格式）→ 以原图为垫图生成角色图，宽高比 `3:4`，追加 `realistic photo, high quality, studio lighting, solid color background`
2. **无参考图**：基于描述构造英文 prompt → 图片生成，`3:4`
3. ⏸ 用户确认

**产出**：`./{project_name}/character.jpg`

---

## 阶段三：换脸写真生成

1. 获取模板图（用户提供或 `image_search` 搜索）
2. 若模板图含数字人 PiP 小画面，用 `read_media` 仅分析背景风格，忽略数字人区域
3. 换脸生成（≤3 张逐张，>3 张批量）：`image_paths=[character.jpg, 模板图]`，prompt 要求保留姿势/服装/背景/光线，仅替换面孔

**生成后 Review（必须执行，不合格重新生成）**：

| 检查项 | 不合格处理 |
|--------|------------|
| 无文字水印 | prompt 加 `remove all text, no text in image` |
| 风格统一 | 统一场景/光线描述重新生成 |
| 人物一致 | 重新生成 character.jpg 或更换垫图 |
| 肤色一致 | prompt 加 `same skin tone, consistent skin tone throughout entire body` |

4. ⏸ 用户确认

**产出**：`./{project_name}/photos/photo_0N.jpg`

---

## 阶段四：口播制作

1. **脚本**：需求中已有则直接用；无则自动生成：
   > `I was shocked at how I looked in the [主题] photoshoot — I got them in one click. No budget, no makeup, just download Hilo AI, upload a selfie, get studio-level photos in seconds! Try it yourself!`

2. **生成语音**：`audios_generation`，调用 `get_voice_id` 按角色性别/风格选声音
3. **获取时间戳**：`audio_transcribe_lyrics` → 写入 `voiceover_subtitle.json`（禁止手动拆分时间戳）

**产出**：`voiceover.mp3` / `voiceover_script.txt` / `voiceover_subtitle.json`

---

## 阶段五：数字人生成

> ⚠️ 三步必须完整执行（绿幕生成 → 口型同步 → 抠像），严禁跳过抠像直接叠加带背景的数字人，否则最终视频报废。

**Step 1：生成绿幕肖像**
- 若服装含绿色调，改用蓝幕（`#0000FF`），Step 3 同步调整 chromakey 颜色
- prompt 指定：`#00FF00 solid green screen background, half-body portrait`
- 输出：`digital_person/green_screen.jpg`

**Step 2：口型同步视频**
- **方案 A（首选）**：Kling Avatar，`image_path=green_screen.jpg`，`audio_path=voiceover.mp3`
- **方案 B（仅 A 明确失败后启用）**：Seedance 2.0，生成 2 段各 15s，`generate_audio: true`，不传 `reference_audio_urls`，prompt 描述自然说话动作与绿幕背景

**Step 3：抠像**
- 调用 `scripts/green_screen_keying.py --input talking_head_green.mp4 --output pip_clean.mov`
- 先输出前 5s demo 让用户确认抠像效果，通过后处理完整视频

**⚠️ 强制自查（用户确认前必须通过，不通过禁止展示）**：

```python
import numpy as np, subprocess
from PIL import Image
for t in [0.5, 2.0, 5.0]:
    subprocess.run(["ffmpeg","-y","-i","digital_person/pip_clean.mov",
                    "-ss",str(t),"-frames:v","1",f"/tmp/chk_{t}.png"], capture_output=True)
    alpha = np.array(Image.open(f"/tmp/chk_{t}.png"))[:,:,3]
    print(f"t={t}s visible={(alpha>10).sum()*100//alpha.size}% maxAlpha={alpha.max()}")
# 可见像素 < 5% 或 maxAlpha=0 → 过度抠像；降级方案：改用 talking_head_green.mp4 + chromakey 实时抠像（参数见 spec.md）
```

**产出**：`digital_person/green_screen.jpg` / `talking_head_green.mp4` / `pip_clean.mov`

> 📖 PiP 合成参数（缩放/坐标/图层顺序）见 [`references/spec.md → 数字人 PiP 规范`](references/spec.md)

---

## 阶段六：教程段制作

**目标**：5.5s 教程段（seg1=1.5s + seg2=2.0s + seg3=2.0s），1080×1920

**Step 1：tut_002 — App 首页截图 + 微振动**
- image agent **editing** `{skill_root}/assets/tut_002_layout_ref.png`：将某一模板卡片替换为本项目模板画面，添加紫色矩形发光边框（`neon purple glow rectangular border`），其余界面保持不变；模板画面未知则向用户询问
- PIL 帧动画制作 2s 微振动：`dy = 4·e^{-2.5t}·sin(2π·7t)`，30fps → `tut_002_v.mp4`

**Step 2：tut_004 — 角色上传弹出动画**
- 底图：`assets/tut_003.png`（空白）/ `assets/tut_004.png`（已上传），照片区坐标 `PX1=288,PY1=288,PX2=791,PY2=1192`
- 弹出动画（2s，30fps）：0~0.3s 空白 → 0.3~0.55s 从 1.35× 缩到 1.0× 带白色闪光 → 0.55s 后冻结
- 叠加 whoosh 音效（`adelay` 对齐至 0.3s）→ `tut_004_v.mp4`

**Step 3：标准化 + 拼接**
- 调用 `scripts/tutorial_synthesis.py pipeline`
- 完整 ffmpeg 命令见 [`references/spec.md → 教程段拼接命令`](references/spec.md)

⏸ 用户确认 → 产出 `tut_combined.mp4`

---

## 阶段七：基本拼接

**视频结构（3 段）**：写真切换(3-4s, xfade 转场) → 写真3+教程段叠加(8-12s) → 尾板(5s)

> ℹ️ 数字人 PiP 与字幕在阶段八叠加，本阶段只拼接基本素材。

**⚠️ 拼接前必须统一流规格**：time_base / 声道数 / 帧率不一致会导致时长翻倍或音频静音。所有文件统一编码为 `libx264 / 30fps / 1080×1920 / aac 48kHz stereo`。

完整标准化命令见 [`references/spec.md → 拼接标准化命令`](references/spec.md)。concat list 必须用**绝对路径**。

调用 `scripts/composite.py image`，用 `ffprobe` 核查时长/分辨率/音频轨。

**产出**：`final_v*.mp4`（无字幕/数字人/BGM）

---

## 阶段八：最终合成

> ⚠️ 字幕、数字人 PiP、BGM 三者必须全部叠加后再展示给用户。

**Step 1：生成 BGM** — audio agent，upbeat pop/electronic 无人声，时长 = 视频时长+3s，末尾 fade out 3s

**Step 2：PIL 字幕 MOV** — Arial Black 全大写，白色+橙红描边(210,70,10) stroke=4，自适应字号(56→22pt 最大宽756px)，底边 y=1344，逐句单行显示。完整渲染代码见 [`references/spec.md → 字幕渲染`](references/spec.md)

**Step 3：ffmpeg composite** — 图层顺序：底层视频 → 字幕 → 数字人 PiP（最顶层）

chromakey：先采样角落像素实测绿幕颜色（勿硬编码），**similarity ≤ 0.10**（深色皮肤临界值，≥0.15 开始误抠人物），blend=0.02，scale=400:-2，位置 x=0:y=H-h，`enable='lte(t\,{vo_end})'`。完整 filter_complex 见 [`references/spec.md → composite filter_complex`](references/spec.md)

**Step 4：强制自查（展示前必须通过）**

```python
import numpy as np, subprocess
from PIL import Image
subprocess.run(["ffmpeg","-y","-i","final.mp4","-ss","3","-frames:v","1","/tmp/pip_chk.png"], capture_output=True)
pip = np.array(Image.open("/tmp/pip_chk.png").convert("RGB"))[1380:1920, 0:400]
print(f"PiP std={pip.std(axis=(0,1)).astype(int)}")
# std dev R < 5 → 数字人不可见，禁止展示
# 排查顺序：1.similarity过大 2.图层顺序错误 3.enable表达式错误 4.pip_clean.mov alpha全零
```

**产出**：`final.mp4`（9:16，含字幕+数字人+BGM）/ `final_4x5.mp4`（可选）

---

## 共享素材

路径：`{skill_root}/assets/`，视频文件由阶段一预检自动下载。

| 文件 | 说明 |
|------|------|
| `endcard_en.mp4` | 5s 英文尾板（Hilo AI 搜索框 CTA） |
| `tut_001.mp4` | App Store 页面（1.5s） |
| `tut_003.png` | Use Template 空白上传界面 |
| `tut_004.png` | Use Template 已上传界面 |
| `tut_002_layout_ref.png` | App 首页布局参考截图 |
| `subtitle_style_ref.jpg` | 字幕样式参考图 |

> 📖 详细技术规范（ffmpeg 命令 / 字幕渲染 / PiP 坐标 / 音频混合）见 [`references/spec.md`](references/spec.md)