Communitygithub.com

Adnan36dan/ugc-video-skill

根据人物面部照片、产品照片和脚本,创建超逼真的20-60秒UGC风格竖版视频(适用于Instagram Reels、YouTube Shorts、Meta广告),用于Vansaar 45+产品。AI角色在真实的印度家庭环境中对着手机摄像头说话、手持产品,包含B-roll切换、逐字字幕(英语、印地语或Hinglish)、AI披露标签和品牌结尾卡片。

ugc-video-skill 是什么?

该技能可将一张面部照片、一张产品照片和一段脚本转化为超逼真的UGC风格竖版视频(9:16,1080×1920,30 fps),时长20-60秒。视频模拟一位45岁以上印度顾客在家中用手机拍摄的效果。Claude充当导演,编写拍摄计划、检查声明合规性、审核所有图像,并驱动一个打包的Python引擎(`scripts/ugc.py`)。该引擎调用fal.ai上的AI模型(如ElevenLabs用于语音合成、Nano Banana Pro用于生成关键帧、OmniHuman 1.5用于生成说话片段、Kling 3用于生成B-roll),并通过ffmpeg进行剪辑。工作流程包括:输入采集、脚本优化与合规检查、拍摄计划制定、语音和关键帧生成(低成本)、说话片段生成(高成本)、最终组装与QA。用户需自行设置fal.ai API密钥,并遵守严格规则:面部必须可授权使用、必须保留AI生成标签、声明必须安全(尤其是阿育吠陀类产品)、在每次付费阶段前需确认。技能支持英语、印地语及Hinglish字幕,并提供多种语音选择(包括ElevenLabs的印度口音)。所有结果均缓存至job文件夹的`state.json`,避免重复付费。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Adnan36dan/ugc-video-skill/tree/HEAD/vansaar-ugc-video

在你喜欢的 AI 中提问

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

文档

Vansaar UGC 视频

面部照片 + 产品照片 + 脚本 → 一段 9:16、1080×1920、30 fps 的 MP4 视频,看起来像一位 45 岁以上的印度顾客在家用手机拍摄的。Claude 担任导演:它编写计划、检查声明、审核每一张图像,并驱动一个打包的 Python 引擎 (scripts/ugc.py),该引擎调用 fal.ai 上的 AI 模型并使用 ffmpeg 进行剪辑。

脚本 ─► 语音 (ElevenLabs) ─► 单词时间戳 ─► 紧凑的停顿 ─► 每个镜头对应一段音频切片
面部+产品 ─► 关键帧 (Nano Banana Pro) ─► 说话片段 (OmniHuman 1.5) / B-roll (Kling 3)
所有内容 ─► 跳接剪辑 + 手持抖动 + 手机滤镜/颗粒感 + 手机麦克风音频
          ─► 字幕 + AI 标签 + 结尾卡片 (真实产品照片) ─► QA ─► final.mp4

基本原则

这些规则保护品牌和视频中的人物。在遇到相关情况时向用户解释,不要直接拒绝。

  1. 面部必须可合法使用。 它必须是 AI 生成的角色,或已书面授权将其肖像用于广告的真实人物。不得使用名人、网红、医生或公众人物,也绝不能使用未经同意拍摄的人。如果你不确定面部来源,请询问一次。
  2. 保留“AI 生成”标签。 默认已开启,为顶部的一个小标签。ASCI 的虚拟影响者指导原则和平台的 AI 内容规则都要求此标签。“逼真”意味着精湛的工艺,而非欺骗观众。如果用户希望移除它,向他们解释规则要求,并将决定权留给他们的合规负责人 (disclosure.show: false)。
  3. 声明必须安全。 阿育吠陀产品受《药品与神奇疗法法》和 ASCI 健康声明规则约束。在生成任何内容之前,先运行 check,然后重写每个 HIGH 标记,并向用户标明每个 MEDIUM 标记。AI 角色绝不能描述自身的健康结果(例如“我的血糖降下来了”):这属于捏造的推荐。它可以谈论日常使用、成分、口感和便利性。详情见 references/compliance-india.md。
  4. 仅在获得“许可”后才进行付费操作。 语音和关键帧成本几分钱;说话片段成本几美元。在下方两个检查点处暂停,并在每个付费阶段前显示成本。
  5. 切勿让用户在聊天中粘贴 API 密钥。 引导他们完成设置步骤(.env 文件、在他们自己的终端中运行 setkey,或他们的环境设置)。

配置(每台机器/会话一次)

SKILL_DIR 是包含此文件的文件夹。作业放置在一个用户可打开的文件夹中:在 Claude Code 中使用当前项目中的 ./ugc_jobs/<slug>;在 claude.ai 聊天中使用 /mnt/user-data/outputs/ugc/<slug>。

pip install -r "$SKILL_DIR/requirements.txt"     # 如果 pip 拒绝,请添加 --break-system-packages
python3 "$SKILL_DIR/scripts/ugc.py" doctor        # 检查 Python 库、ffmpeg+libass、字体、密钥、网络
  • 没有 fal.ai 密钥。 告诉用户在 fal.ai(控制台 → 密钥)创建一个密钥并充值(10-20 美元足够制作几个视频)。然后他们通过以下三种方式之一自行存储:在 Claude 运行的文件夹中创建一个包含 FAL_KEY=... 的 .env 文件;在他们自己的终端中运行 python3 scripts/ugc.py setkey;或者在云会话中,在环境设置中设置环境变量 FAL_KEY。
  • 网络被阻止(doctor 显示“无法访问 fal.ai”)。沙箱需要允许访问 queue.fal.run、rest.fal.ai、*.fal.media、storage.googleapis.com,以及用于直接语音选项的 api.elevenlabs.io。准确告知用户这些信息。修改位置见 references/troubleshooting.md。
  • ffmpeg 缺失。 参见 references/troubleshooting.md。
  • 免费试用。 python3 "$SKILL_DIR/scripts/ugc.py" demo --out <文件夹> 使用离线模拟 (--mock) 运行整个流程。它可以在不花费任何费用的情况下证明安装成功。

工作流程

运行命令格式:python3 "$SKILL_DIR/scripts/ugc.py" <命令> --job <作业文件夹>。每个付费结果都会缓存在作业的 state.json 中。重新运行命令不会为相同输入重复付费,中断的请求将在下次运行时恢复。

1. 输入采集

你需要三个输入:面部图像、产品图像和脚本。在一次消息中询问任何缺失的内容,以及你无法推断的信息:

  • 语言:英语,或印地语/ Hinglish
  • 产品的准确名称
  • 目标时长(默认:脚本自然所需时长,20-60 秒内)
  • 人物的性别或语音偏好
  • 任何场景偏好(默认:阳光充足的印度公寓)

如果存在疑问,在此处确认面部同意书。

然后,你本人查看两张图像:

  • 面部。 编写 character.description:大致年龄、发型、肤色、显著特征和衣着。这会在每个提示中强化身份。如果照片分辨率低、侧脸或眼镜、手部、口罩遮挡,请要求提供清晰的正面照片,因为唇形同步质量取决于此。
  • 产品。 检查标签是否清晰可读。注意背景是纯白还是透明(结尾卡片可以抠图)还是复杂(结尾卡片以卡片形式显示)。如果用户有透明的 PNG 产品照,请索要。

2. 脚本处理

使用 --face、--product、--script(或 --text)、--lang、--title 和 --product-name 运行 init。然后运行 check --job <job>。

使用 references/script-and-voice.md 将脚本改写为口语化的 UGC:

  • 前 2 秒内设置钩子
  • 短句口语
  • 每个片段一个想法
  • 一个温和的行动号召

修复每个 HIGH 标记的声明,同时保留用户的原意。长度大约每秒 2.5 个单词,因此 20 秒约 50 个单词,60 秒约 150 个单词。对于印地语,使用天城文书写 say(英文品牌词可以保留拉丁字母),因为 TTS 发音效果更好。如果用户想要 Hinglish 字幕,则同时提供罗马字母的 caption。

3. 计划

编辑 plan.yaml。字段参考见 references/plan-reference.md;完整的工作示例见 templates/plan.example.yaml。使其感觉真实的要素(详情见 references/realism-playbook.md):

  • 在家中的 2-3 个场景(例如沙发中景、沙发特写、厨房产品)。看起来像一个人拍摄了几个镜头,而不是专业制作。
  • 说话片段时长 2-8 秒。 相同场景的连续片段会自动进行跳接放大。
  • 每 2-3 个说话片段插入一个 B-Roll:倒水的手部特写、柜台上的产品、清晨散步。B-roll 可以隐藏剪辑并恰当地展示产品。对于产品特写,使用 with_person: false,这样就不会重复生成人脸。
  • 最多在一个场景中手持产品 (framing: product)。人物做手势时产品可能变形,因此让 B-roll 和结尾卡片来展示产品。
  • 为每个片段提供一个简短的 performance 提示,以匹配台词的语气。
  • 结尾卡片放在最后。 真实的产品照片和真实的标志在此处合成,因此标签始终正确。
  • 语音。 使用 references/script-and-voice.md 进行选择。fal 的预设语音主要是美式或英式英语。如需印度口音,请使用 provider: elevenlabs 并选择 ElevenLabs 语音库中的印度语音,或使用 provider: file 配合真实录音(这是最逼真的选项)。

然后运行 validate(修复所有错误)和 estimate。

检查点 1。 发送一条包含以下内容的消息:

  • 片段表格(id、镜头、场景、台词)
  • 被标记的声明以及你做出的修改
  • 语音选择
  • 每个场景一行描述
  • 预估长度和成本

询问“可以继续吗?”,在用户确认前不要继续。

4. 语音和关键帧(低成本)

运行 voice。阅读长度表。如果出现“文本仅匹配 N%”的警告,说明 TTS 发音错误或跳词:重写该行(拼出数字、使用天城文),然后运行 voice --only <id> --force。如果总时长超出 20-60 秒范围,则精简脚本或调整 voice.speed(0.9-1.15)。

运行 frames,然后打开 work/frames/contact.jpg 和 work/frames/<key>/ 中的全尺寸候选图像。对照 references/realism-playbook.md 中的关键帧检查清单审核每一张:身份与面部照片匹配、自然肤色、正确的手部、产品标签与产品照片匹配、真实的家庭环境、手机摄像头光线。将 pick: 设置为最佳候选。如果没有合格的,完善场景或描述,然后运行 frames --only <setup> --force。每个场景最多进行两轮,然后向用户展示问题所在。

检查点 2。 发送 work/voice/vo_preview.mp3 和接触片,说明你选择了哪些候选及其原因,并告知说话片段的成本(昂贵部分)。等待确认。稍后更改语音意味着需要重新制作说话片段。

5. 片段

运行 clips。说话片段每个大约需要 1-5 分钟,每次同时运行 3 个。如果某个片段失败,其他片段会被保留,因此重新运行 clips 只会重试失败的片段。确保没有警告说某个片段时间短于其音频。

6. 组装和 QA

运行 assemble,然后运行 qa。打开 out/<slug>_contact.jpg 并检查:

  • 镜头间无面部漂移
  • 无变形的的手部或产品
  • 字幕不遮挡嘴巴或产品标签
  • 结尾卡片文字清晰可读

如果某个片段不好,运行 clips --only <id> --force,然后再次运行 assemble。修复 QA 报告的每一个 FAIL;检查每一个 CHECK。

7. 交付

发送 out/<slug>.mp4(以及接触片,如果有用)。用 3-5 行内容说明:

  • 长度和预估花费(state.json 中记录了累计总额)
  • 任何仍需用户合规负责人批准的声明
  • AI 标签已开启
  • 最可能改进下一个视频的一两个调整

如需同时为编辑人员生成无字幕的副本,请设置 captions.clean_copy: true。

快速修复

症状修复方案
面部看起来不像照片更丰富的 character.description、candidates: 3、更清晰的正面源照片
塑料感或美颜滤镜皮肤重新生成;在场景中避免使用“美丽/完美无瑕”;保持 grain ≥ 0.4
产品标签扭曲模糊重新生成该关键帧,或者从说话场景中移除产品(由结尾卡片 + B-roll 展示)
嘴唇漂移或嘴部模糊更短的片段(≤ 6 秒)、显示嘴部的正面关键帧、尝试 config/models.yaml 中的 Kling Avatar 模型
机器人语音降低 stability (0.35-0.45)、用逗号表示呼吸、使用真实录音或 eleven-v3 模型
太慢/太长finish.tighten_pauses: 0.22、voice.speed: 1.08、删减词语
B-roll 看起来假更简单的动作(一个动作)、with_person: false、或在优秀静止画面上使用 motion: kenburns

更多内容见 references/troubleshooting.md。

参考文件(需要时阅读)

  • references/realism-playbook.md:使 AI UGC 看起来真实的关键要素;关键帧和最终视频审核检查清单。在规划场景和审核图像前阅读。
  • references/script-and-voice.md:面向 45 岁以上印度观众的 UGC 脚本结构,为 TTS(印地语/Hinglish)编写、选择并调整语音、脚本示例。
  • references/compliance-india.md:肖像同意书、AI 披露、DMR Act / ASCI 声明规则、安全措辞表。在 check 标记任何内容时阅读。
  • references/plan-reference.md:每个 plan.yaml 字段。
  • references/models-and-costs.md:每个模型的用途、价格、如何替换为更新的模型。
  • references/troubleshooting.md:安装、密钥、网络白名单、API 错误、修复方案。

相关技能