HyperFrames 管线 — 多租户品牌解说视频
端到端管线,接收一个 URL 并生成完整的品牌解说/宣传 MP4 视频。基于 ColdStart (coldstartb2b.com) 构建和验证。设计为可扩展到任何 B2B 品牌,每租户配置最少。
何时调用
- 用户说 "Hyper Frames" / "hyperframes" + URL 或品牌名称
- 用户要求为特定业务制作解说/宣传视频
- 用户说 "make a video for " 或类似内容
- 用户说 "let's try this on "
所需环境(位于 <your-project-dir>/.env 中)
KIE_AI_API_KEY=... # 通过 KIE.AI 使用 Nano Banana 2 + Seedance 2
HEYGEN_API_KEY=... # HeyGen 虚拟人生成
ELEVENLABS_API_KEY=... # 11Labs 语音 + 音乐
项目布局
<your-project-dir>/
brands/
<brand>/ # 每个品牌一个目录(由 brand-book 创建)
brand.json
colors.md
typography.md
voice-tone.md
reference.png
template-16x9/ # 活跃的合成文件(单个工作目录;每品牌交换资产)
index.html
styles/
brand.css # 品牌界面 — 唯一包含品牌特定 CSS 的文件
template.css # 品牌无关的运动效果
layouts.css # 10 布局系统
assets/
voice.mp3 # 11Labs 输出(已填充)
avatar.webm # HeyGen 输出(已抠像并填充)
music.mp3 # 11Labs Music 背景音乐
broll-*.png # Nano Banana B-roll 图片
renders/
对于多租户生产,未来的 Stage 0 应该为每个品牌复制 template-16x9/。目前,每次渲染时原地替换资产。
管线阶段
阶段 1 — 品牌提取
在目标 URL 上调用 brand-book 技能。它会产生:
brands/<brand>/brand.json— 调色板、排版、语音/语调摘要brands/<brand>/css-variables.json— 来自实时网站的所有 CSS 变量brands/<brand>/reference.png— 首页截图
提取驱动所有下游阶段的两个锁定颜色:
bg:品牌的背景颜色(通常接近黑色,例如#050508)accent:品牌的信号颜色(通常是饱和色调,例如#8b9cf7)
这些将替换 B-roll 提示和 styles/brand.css 中的内容。
阶段 2 — 阅读网站,了解业务
使用 WebFetch 读取首页和关键页面(服务、团队、定价、关于)。综合:
- 他们销售什么
- 他们销售给谁(理想客户画像 ICP)
- 1-2 个最鲜明的差异化因素
- 期望的行动号召 CTA(预约通话、开始试用等)
这成为脚本的内容。
阶段 3 — 脚本
为请求的时长编写脚本。节奏规则:语音大约每秒 2.7 个单词(multilingual_v2 节奏)。因此 22 秒 ≈ 60 词;45 秒 ≈ 120 词;60 秒 ≈ 160 词。
结构(22 秒时使用 5 场景模板;更长时间按比例缩放):
- 钩子(时长的 10–15%)— 3-6 个词的有力句子
- 正文 1 — 问题(约 30%)— 问题所在 / 瓶颈
- 正文 2 — 数据或证明(约 15%)— 重要性(B-roll 使用模板 2 图表)
- 正文 3 — 我们的工作方式(约 25%)— 差异化因素
- 结尾 / CTA(约 15%)— 邀请 + 品牌标志
对于更长的视频(45 秒以上),在正文 1 和正文 2 之间添加额外的正文场景(例如“正文 1a — 具体痛点”、“正文 1b — 不行动的成本”)。
11Labs eleven_multilingual_v2 的韵律: 标点驱动节奏(逗号 = 微停顿,句号 = 完全停顿,破折号 = 节拍)。无需处理 SSML 或情感标签 — multilingual_v2 不识别它们。只需用自然标点编写对话式散文。
将脚本保存到 template-16x9/script.txt 以便追溯。
阶段 4 — 语音(11Labs)
使用 eleven_multilingual_v2 调用 11Labs TTS。默认语音:<your-elevenlabs-voice-id>(将此设置为 11Labs 库中的语音,或用户指定/品牌偏好的语音 — 如果不清楚则询问)。
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/<your-elevenlabs-voice-id>" \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"<script>","model_id":"eleven_multilingual_v2"}' \
--output assets/voice_raw.mp3
通过 FFmpeg 将音量后处理为 92%(管线标准):
ffmpeg -y -i voice_raw.mp3 -af "volume=0.92" -c:a libmp3lame -b:a 192k voice.mp3
阶段 5 — 虚拟人(HeyGen)
选择一个 talking_photo_id(外观 ID)。将默认值设置为您自己 HeyGen 账户中的外观:<your-heygen-talking-photo-id>。
始终在角色级别设置 use_avatar_v_model: true。如果外观未注册 V 模型(V-enrolled),HeyGen 会静默回退到 Avatar IV(Avatar IV 输出渲染正常)。
上传音频 → 提交 talking_photo 渲染 → 轮询 → 下载 → 抠像:
# 上传音频
AUDIO_ID=$(curl -s -X POST "https://upload.heygen.com/v1/asset" \
-H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: audio/mpeg" \
--data-binary @assets/voice.mp3 | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['id'])")
# 提交渲染
VID=$(curl -s -X POST "https://api.heygen.com/v2/video/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: application/json" \
--data-binary @- <<EOF | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['video_id'])"
{
"video_inputs": [{
"character": {
"type": "talking_photo",
"talking_photo_id": "<your-heygen-talking-photo-id>",
"use_avatar_v_model": true
},
"voice": { "type": "audio", "audio_asset_id": "$AUDIO_ID" },
"background": { "type": "color", "value": "#00FF00" }
}],
"dimension": { "width": 720, "height": 1280 }
}
EOF
)
# 轮询直到完成(IV 通常需要 60–90 秒,使用新外观首次渲染 V 模型需要 5–20 分钟)
# GET https://api.heygen.com/v1/video_status.get?video_id=$VID → data.status == "completed"
# 然后下载 data.video_url 到 assets/avatar_green.mp4
阶段 6 — 抠像 + 对称填充
将 HeyGen 绿幕 MP4 转换为透明的 VP9 webm,两端各添加 0.5 秒冻结帧填充:
# 抠像 + 去绿 → 原始透明 webm
ffmpeg -y -i avatar_green.mp4 \
-vf "chromakey=0x00FF00:0.10:0.05,despill=type=green:mix=0.6:expand=0" \
-c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
avatar.raw.webm
# 两端各添加 0.5 秒冻结帧填充(保持 Alpha 通道)
ffmpeg -y -c:v libvpx-vp9 -i avatar.raw.webm \
-vf "tpad=start_duration=0.5:start_mode=clone:stop_duration=0.5:stop_mode=clone" \
-c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
avatar.webm
在 voice.mp3 两端对称填充 0.5 秒静音,使音频偏移与虚拟人时间匹配:
ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t 0.5 -c:a libmp3lame -b:a 192k silence.mp3
ffmpeg -y -f concat -safe 0 -i <(printf "file '%s/silence.mp3'\nfile '%s/voice_raw.mp3'\nfile '%s/silence.mp3'\n" "$PWD" "$PWD" "$PWD") \
-c:a libmp3lame -b:a 192k voice.mp3
这实现了时间规则:虚拟人出现 → 语音开始 → 语音结束 → 虚拟人淡出。请参阅 project_audio_video_timing.md(如果在阶段 9 中缺失则创建 — 规则是 0.5 秒前导 + 0.5 秒尾部,所有 GSAP 场景提示偏移 +0.5 秒,最终淡出在语音结束后 0.1 秒开始)。
阶段 7 — 对象位置校准
虚拟人面部在画面中的位置取决于源照片,因此每个外观 ID 都需要重新校准:
ffmpeg -y -ss 0.7 -i avatar.webm -vframes 1 avatar-frame-check.png
读取画面,测量面部中心 y 坐标(在 1280 高度的源中)。根据布局计算 object-position:
object_position_y_pct = ( (face_y_px / 1280) * scaled_height_for_layout - layout_slot_height/2 ) / (scaled_height_for_layout - layout_slot_height) * 100
实践中:面部位于画面上三分之一(face_y ~380)→ 对于紧凑插槽使用 '50% 30%',对于全画幅插槽使用 '50% 50%'。在 index.html 中更新 LAYOUT_AVATAR_SLOTS。绝不要猜测 — 始终从提取的画面进行校准。
阶段 8 — B-roll 图片(通过 KIE.AI 使用 Nano Banana 2)
两个固定模板 — 请参阅 project_image_direction_templates.md 了解完整版本。品牌颜色在每个项目中替换(从 brand.json 替换 BG_HEX 和 ACCENT_HEX)。
模板 1 — 纯抽象雕塑(氛围、情绪、叙事节拍):
在纯
[BG_HEX]背景上的抽象 3D 雕塑渲染。[FORM_DESCRIPTION],暗示[MOTION_INTENT]。[ACCENT_HEX]的光线穿透并围绕形态折射,带有次表面散射,在略微反光的深色地板上投射出柔和焦散。柔和的定向工作室灯光。超写实 Octane 渲染。高端科技主题美学。中央形态对焦清晰,边缘向阴影过渡。无文字,无徽标。
模板 2 — 玻璃图表(任何提及统计、比较、增长、比率、“X×”、“Y%”的台词):
在纯
[BG_HEX]背景上的抽象 3D 数据可视化。[CHART_TYPE]完全由漂浮的半透明玻璃形态渲染,描绘[DATA_CONCEPT]。基础元素采用哑光灰玻璃;焦点元素以[ACCENT_HEX]的次表面散射和折射发光,在略微反光的深色地板上投射出柔和焦散。一条细的灰白色轴线。柔和的定向工作室灯光。超写实 Octane 渲染。高端科技主题美学。极简编辑构图,留有充足留白。无文字,无数字,无标签,无徽标。
每场景决策规则:如果脚本台词引用数字/统计/比较 → 模板 2。否则 → 模板 1。
提交模式(默认 1:1 比例;支持任意比例)。始终捕获 HTTP 状态码和响应体,以便 4xx 错误自诊断:
source .env && RESPONSE=$(curl -sS -w "\nHTTP_CODE:%{http_code}" -X POST "https://api.kie.ai/api/v1/playground/createTask" \
-H "Authorization: Bearer $KIE_AI_API_KEY" -H "Content-Type: application/json" \
--data-binary @- <<EOF
{"model":"nano-banana-2","input":{"prompt":"<TEMPLATE WITH SLOTS FILLED>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "KIE 提交失败 — 请查看上方响应体"; exit 1; }
每 4 秒轮询 https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id> 直到 data.state == "success",解析 data.resultJson(它是一个 JSON 字符串 — 用 json.loads() 解析),下载 URL 到 assets/broll-N.png。
并行运行多个 B-roll 生成 — KIE.AI 能很好地处理并发任务。
常见的 400 错误原因:提示安全过滤器。 Nano Banana 2 拒绝被识别为涉及法律/暴力/冲突的提示(例如“法庭”、“法律斗争”、“原告 vs 被告”)。严格保持在两个抽象模板内 — 通过几何/颜色传达含义,绝不要使用字面主题。经验证(2026-04-28):最小抽象探测返回 200 并使用相同的认证/模式,因此这里的 400 几乎总是提示内容问题。
阶段 9 — 背景音乐(11Labs Music)
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/music?output_format=mp3_44100_128" \
-H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
-d '{
"prompt": "<MUSIC PROMPT>",
"music_length_ms": 22000,
"force_instrumental": true,
"model_id": "music_v1"
}' --output assets/music_raw.mp3
同步返回音频字节。music_length_ms 匹配合成时长(范围 3000–600000ms)。
默认音乐提示用于 B2B 广告宣传背景(经验证 2026-04-27):
为 B2B 商业广告制作的乐观向上器乐背景音乐。明亮的现代钢琴演奏向前推进的节奏模式,带有清脆断奏音符,配合微妙的提升合成器音垫。轻柔的脉搏 — 柔和的沙锤或闷敲的节奏咔哒声提供稳定的前进动力。无大鼓,无底鼓,无镲片,无钹。无人声。自信、活泼、充满活力、乐观的感觉。现代、干净、科技前沿、专业、当代企业风格。速度约 115 BPM。明亮的大调,阳光但不甜腻。整曲动态均匀 — 无增强、无停顿、无高潮、无淡入淡出 — 但保持稳定的节奏动力。听起来像现代 SaaS 产品发布视频的背景音乐。
提示中应避免的反模式:
- “电影感” / “情绪化” / “环境音乐” → 产生感伤拖沓,不适合广告宣传
- 低于 90 BPM 的速度 → 太催眠
- 提及增强、高潮、动态变化 → 与语音冲突
- 忘记“无人声” → ElevenLabs 可能添加哼唱
混音至 -20dB 并添加简短淡入淡出,使其在语音下方不显眼:
ffmpeg -y -i music_raw.mp3 \
-af "volume=-20dB,afade=t=in:st=0:d=0.4,afade=t=out:st=<end-0.6>:d=0.6" \
-c:a libmp3lame -b:a 192k music.mp3
阶段 10 — 合成组装
template-16x9/index.html 是工作合成文件。对于每次渲染:
- 将根元素、语音、虚拟人和音乐元素的
data-duration更新为目标时长 - 更新
styles/brand.css中的品牌颜色(变量--bg、--accent等) - 如果品牌使用不同字体系列,在
brand.css中更新字体 - 重新调整 GSAP 时间线中的场景过渡以匹配脚本节拍
- 确保所有 4 个定时元素(虚拟人视频、语音音频、音乐音频、根合成)具有对齐的
data-start和data-duration
音轨索引:avatar=1、voice=2、music=3。所有音轨类名为 class="clip"。所有 data-start="0"。
阶段 11 — 渲染
cd "$HOME/<your-project-dir>/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output renders/<brand>-v<n>.mp4
关键:在前台运行渲染。 后台模式的渲染在帧捕获开始后会在 0% CPU 处挂起。使用带 timeout: 300000 的前台 Bash 调用。22 秒合成渲染约需 1–2 分钟,45 秒约需 3–4 分钟。
渲染完成后,使用 open -a "QuickTime Player" renders/<brand>-v<n>.mp4 进行审查。
迭代循环
大多数渲染需要 1–3 次迭代:
- v1:用合理的默认值端到端跑通整个链条
- v2:修复明显问题(面部裁剪、音乐太响、过渡错位等)
- v3:微调美学(脚本措辞、B-roll 提示、音乐提示、虚拟人位置、过渡时序)
故障排除
阶段 8(KIE 400)
始终捕获 HTTP 状态码和响应体。常见的 400 错误原因是 Nano Banana 2 的安全过滤器对被视为法律/暴力/冲突的提示敏感。解决方案:使用抽象模板(模板 1 或 2),通过几何/颜色表达含义。如果您收到 400,请尝试最小提示,例如“在黑色背景上的抽象 3D 形状”以确认认证和模式有效。如果最小提示返回 200,则问题在于提示内容。
阶段 5(HeyGen 超时)
虚拟人 V 模型的首次渲染可能比预期更长(5–20 分钟)。轮询最多 20 分钟,每次间隔 10 秒。始终捕获完整的 JSON 响应以进行诊断。
阶段 4(11Labs 语音)
如果语音听起来不自然,检查脚本是否有连读(例如“don't”而不是“do not”等缩写)。multilingual_v2 在对话式节奏下效果最佳。
阶段 11(HyperFrames 渲染)
- 如果渲染挂起,检查合成文件中的
data-duration是否正确,并与脚本匹配 - 确保所有资产文件存在且命名正确
- 如果渲染速度太慢,降低输出分辨率或帧率
未来规划(Stage 0 及更高)
- Stage 0:复制
template-16x9/为每个品牌创建独立工作目录,实现真正的多租户 - 自动化测试套件:验证每个阶段输出格式正确
- Web UI:允许非技术用户通过表单触发管线
- 并发渲染:支持同时为多个品牌生成视频
- A/B 测试:为同一品牌生成多个变体,测试不同脚本和风格