HyperFrames 管道 —— 多租户品牌解说视频
端到端管道,接收URL并生成完整的品牌解说/宣传MP4。基于ColdStart(coldstartb2b.com)构建并验证。设计为可扩展到任何B2B品牌,每个租户的配置需求极少。
何时调用
- 用户说出“Hyper Frames”/“hyperframes”加上URL或品牌名称
- 用户要求为特定企业制作解说/宣传视频
- 用户说“为<品牌>制作视频”或类似内容
- 用户说“让我们在<新URL>上试试”
必需环境(在 $PIPELINE_ROOT/.env 中 —— 复制 .env.example)
KIE_AI_API_KEY=... # 通过 KIE.AI 使用 Nano Banana 2 + Seedance 2
HEYGEN_API_KEY=... # HeyGen 虚拟主播生成
ELEVENLABS_API_KEY=... # 11Labs 语音 + 音乐
ELEVENLABS_VOICE_ID=... # 默认旁白语音
HEYGEN_TALKING_PHOTO_ID=... # 默认虚拟主播形象
项目结构
$PIPELINE_ROOT/ # 此仓库根目录
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 音乐背景
broll-*.png # Nano Banana B-roll 图像
renders/
对于多租户生产环境,未来的第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 抓取首页及关键页面(服务、团队、定价、关于)。综合提取:
- 他们销售什么
- 他们的理想客户画像
- 1-2个最突出的差异化因素
- 期望的行动号召
这将成为脚本的核心内容。
第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%)—— 差异化因素
- 结尾 / 行动号召(约15%)—— 邀请 + 品牌标志
对于更长的视频(45秒以上),在正文1和正文2之间增加额外的正文场景(例如“正文1a —— 特定痛点”、“正文1b —— 不作为的代价”)。
11Labs eleven_multilingual_v2 的韵律提示: 标点驱动节奏(逗号=微停顿,句号=完全停顿,破折号=节拍)。无需使用SSML或情感标签 —— multilingual_v2不识别它们。只需编写带有自然标点的会话式散文。
将脚本保存到 template-16x9/script.txt 以便追踪。
第4阶段 —— 语音(11Labs)
调用11Labs TTS,使用 eleven_multilingual_v2。默认语音:来自 .env 的 $ELEVENLABS_VOICE_ID(或用户指定/品牌偏好的语音 —— 如果不确定请询问)。
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/$ELEVENLABS_VOICE_ID" \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"<脚本>","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)。默认使用 .env 中的 $HEYGEN_TALKING_PHOTO_ID(你的HeyGen账户中的任何说话照片形象)。
始终在角色级别设置 use_avatar_v_model: true。如果该形象未启用V模型,HeyGen将默默回退到Avatar IV(未注册的形象回退到IV;渲染不受影响)。
上传语音 → 提交说话照片渲染 → 轮询 → 下载 → 抠像:
# 上传音频
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": "$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
这实现了时间规则:虚拟主播出现 → 语音开始 → 语音结束 → 虚拟主播淡出。(规则为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)
两个固定模板。品牌颜色按项目替换(从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":"<填充了插槽的模板>","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拒绝看起来与法律/暴力/冲突相关的提示(例如“法庭”、“法律斗争”、“原告与被告”)。严格使用两个抽象模板 —— 通过几何/颜色传达含义,绝不使用字面主题。已于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_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 "$PIPELINE_ROOT/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:打磨
使用 brands/<brand>/claude.md 中的渲染反馈日志进行追踪。
设计约束与稳定性保证
- 5场模板结构是为22秒时长优化的。对于更长时长按比例缩放,但始终保持开场钩子 + 问题/解决节奏。
- 语音框裁剪(B框):虚拟主播视频始终以720x1280生成。合成时,裁剪区域(帧内的B框)因形象而异。总是从提取的帧校准
object-position。 - 音频同步:同步边界是严格的。所有填充必须精确对称。
- 音乐混音:-20dB是锁定值。改变它会覆盖语音或暴露背景噪音。
- B-roll生成:始终使用模板1或2。如果安全过滤器触发,不要尝试使用字面提示 —— 回到更抽象的措辞。
- 错误传播:任何4xx/5xx响应都应在继续之前失败,并包含完整的响应体用于调试。
支持的渲染风格
| 风格 | 时长 | 脚本场景 | B-roll数量 |
|---|---|---|---|
| 快速宣传 | 22秒 | 5 | 5 |
| 标准解说 | 45秒 | 6-7 | 6-7 |
| 完整品牌故事 | 60秒+ | 8+ | 8+ |
默认使用22秒快速宣传风格 —— 它非常适合快速吸引注意力,并自然地限制API成本。