Communitygithub.com

HyperFrames 多租户品牌解说视频管线

端到端多租户品牌解说/宣传视频管线。从 URL 生成完整的品牌视频 — 提取品牌标识、编写脚本、生成语音 + AI 虚拟人 + B-roll 图片 + 背景音乐、在 HyperFrames 中组装并渲染。触发短语包括“Hyper Frames for <url>”、“make a Hyper Frames video for <brand>”、“Hyper Frames promo for <url>”、“explainer video for <brand>”或直接说“Hyper Frames <url>”。

HyperFrames 多租户品牌解说视频管线 是什么?

HyperFrames 管线是一个完整的端到端系统,用于从单个 URL 自动生成多租户品牌解说/宣传视频。它通过品牌提取阶段提取品牌的视觉标识(颜色、排版、语调),然后综合网站内容来生成脚本,利用 ElevenLabs 的 TTS 和 HeyGen 的虚拟人生成技术生成画外音和 AI 虚拟人,通过 KIE.AI 的 Nano Banana 2 模型生成 B-roll 图片,并利用 ElevenLabs Music 生成背景音乐。所有资产在 HyperFrames 中组装并渲染为最终的 MP4 视频。该系统专为 B2B 品牌设计,需要最少的每租户配置(仅需环境变量中的 API 密钥),并支持 ColdStart (coldstartb2b.com) 等品牌的完整工作流。其核心优势在于简化的多租户架构:每个品牌的数据存储在独立的 `brands/<brand>/` 目录中,而渲染过程通过替换 `template-16x9/` 目录中的资产来重用单一合成模板。管线包含详细的迭代循环指南和故障排除提示,如 chromakey 后处理、对象位置校准以及 B-roll 提示的安全过滤器规避策略。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ChuchoMonster/claude-code-skills/tree/HEAD/skills/hyperframes-pipeline

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 场景模板;更长时间按比例缩放):

  1. 钩子(时长的 10–15%)— 3-6 个词的有力句子
  2. 正文 1 — 问题(约 30%)— 问题所在 / 瓶颈
  3. 正文 2 — 数据或证明(约 15%)— 重要性(B-roll 使用模板 2 图表)
  4. 正文 3 — 我们的工作方式(约 25%)— 差异化因素
  5. 结尾 / 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 是工作合成文件。对于每次渲染:

  1. 将根元素、语音、虚拟人和音乐元素的 data-duration 更新为目标时长
  2. 更新 styles/brand.css 中的品牌颜色(变量 --bg、--accent 等)
  3. 如果品牌使用不同字体系列,在 brand.css 中更新字体
  4. 重新调整 GSAP 时间线中的场景过渡以匹配脚本节拍
  5. 确保所有 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 测试:为同一品牌生成多个变体,测试不同脚本和风格

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能