Communitygithub.com

Adnan36dan/ugc-video-skill

根據角色臉部照片、產品照片和腳本,製作逼真的20-60秒UGC風格豎版影片(適用於Instagram Reels、YouTube Shorts、Meta廣告),讓AI人物在真實的印度家庭環境中對手機鏡頭說話、展示產品,並包含B-roll剪輯、逐字字幕、AI揭露標籤和品牌尾卡。

ugc-video-skill 是什麼?

此技能專為Vansaar品牌設計,能將一張臉部照片、一張產品照片和一段腳本轉化為高品質的UGC風格豎版影片。它整合了多個AI模型:透過ElevenLabs生成自然語音,利用Nano Banana Pro產生關鍵影格,並使用OmniHuman 1.5與Kling 3等模型創建說話片段和B-roll素材。最終影片包含跳剪、手持晃動、手機等級的畫面顆粒與音質,並自動加上逐字字幕、AI揭露標籤和品牌尾卡。 整套流程由Claude擔任導演,負責規劃分鏡、審查素材、確保法規合規(特別是印度《藥品與神奇療法法》及ASCI健康宣稱規範),並驅動內建的Python引擎執行。使用時需注意:角色臉部必須是AI生成或已取得書面授權的真實人物,不可使用名人或未經同意的照片;AI揭露標籤預設開啟且不得隨意關閉;所有健康或功效宣稱必須先通過合規檢查,AI角色不得假造個人使用見證。 技能支援Claude Code(產出在專案目錄下)與claude.ai對話(產出在掛載目錄下)。使用者需自備fal.ai API金鑰及小額點數(約10-20美元可製作數部影片),並確保網路能連線特定端點。首次使用可執行demo指令(離線模擬模式)免費驗證安裝是否正確,整個流程包含兩個收費檢查點,確保在高成本環節(生成說話片段)前先獲得使用者同意。

相容平台✓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. 收集資料

你需要三個輸入:臉部圖片、產品圖片和腳本。在一個訊息中詢問任何缺少的項目,以及你無法推斷的任何資訊:

  • 語言:英語,或印地語/印度英語混合語
  • 產品的確切名稱
  • 目標長度(預設:腳本自然所需的長度,在 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 的發音效果會好得多。如果使用者想要印度英語混合語字幕,請同時提供羅馬字母的 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。閱讀長度表。如果出現「transcript matches only 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 輪,然後向使用者顯示問題所在。

檢查點 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、更清晰的正面原始照片
塑膠感或美顏濾鏡皮膚重新生成;避免在場景中使用「beautiful/flawless」;保持 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 撰寫(印地語/印度英語混合語)、選擇和調整語音、腳本範例。
  • references/compliance-india.md:肖像同意、AI 揭露、DMR 法案 / ASCI 宣稱規則、安全措辭表。當 check 標記任何內容時閱讀。
  • references/plan-reference.md:plan.yaml 的每個欄位。
  • references/models-and-costs.md:哪個模型做什麼、價格、如何換成較新的模型。
  • references/troubleshooting.md:安裝、金鑰、網路允許清單、API 錯誤、修正方法。

相關技能