Vansaar UGC 비디오은(는) 무엇을 하나요?
얼굴 사진 + 제품 사진 + 스크립트 → 9:16, 1080×1920, 30fps MP4. 45세 이상 인도인이 집에서 휴대폰으로 촬영한 것처럼 보입니다. Claude가 디렉터가 되어 계획을 작성하고, 클레임을 확인하고, 모든 이미지를 검토하며, fal.ai의 AI 모델을 호출하고 ffmpeg로 결과를 편집하는 번들 파이썬 엔진(scripts/ugc.py)을 구동합니다.
script ─► voice (ElevenLabs) ─► word timings ─► pauses tightened ─► one audio slice per shot
face+product ─► keyframes (Nano Banana Pro) ─► talking clips (OmniHuman 1.5) / B-roll (Kling 3)
everything ─► jump-cut edit + handheld drift + phone grade/grain + phone-mic audio
─► captions + AI label + end card (real product photo) ─► QA ─► final.mp4
기본 규칙
이 규칙들은 브랜드와 영상 속 인물을 보호합니다. 해당 내용이 나올 때 사용자에게 설명하고, 단순히 거절하지 마세요.
- 얼굴은 사용 가능해야 합니다. AI가 생성한 캐릭터이거나 광고에 초상使用权을 서면으로 허락한 실제 인물이어야 합니다. 유명인, 인플루언서, 의사 또는 공인은 절대 안 되며, 동의 없이 촬영된 사람도 안 됩니다. 얼굴 출처가 확실하지 않으면 한 번 물어보세요.
- 'AI 생성' 라벨을 유지하세요. 기본적으로 상단에 작은 라벨로 켜져 있습니다. ASCI의 가상 인플루언서 지침과 플랫폼 AI 콘텐츠 규칙이 이를 요구합니다. '현실적'이라는 것은 시청자를 속이는 것이 아니라 훌륭한 제작을 의미합니다. 사용자가 제거를 원하면 규칙이 요구하는 사항을 설명하고, 결정은 규정 준수 담당자에게 맡기세요(
disclosure.show: false). - 클레임은 안전해야 합니다. Ayurveda 제품은 마약 및 마법 치료법법(DMR Act)과 ASCI 건강 클레임 규칙의 적용을 받습니다. 생성 전에 반드시
check를 실행하고, 모든 HIGH 플래그는 다시 작성하고 각 MEDIUM 플래그를 사용자에게 알리세요. AI 캐릭터는 자신의 건강 결과를 설명해서는 안 됩니다("혈당이 내려갔어요"): 이는 조작된 증언입니다. 일상, 성분, 맛, 사용 편의성에 대해 이야기할 수 있습니다. 자세한 내용은references/compliance-india.md를 참조하세요. - '진행' 확인 후에만 비용이 발생합니다. 음성과 키프레임은 저렴하고, 토킹 클립은 비쌉니다. 아래 두 체크포인트에서 중단하고 유료 단계 전에 비용을 표시하세요.
- 사용자에게 채팅에 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에서 "cannot reach 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 <folder>는 오프라인 대체재(--mock)로 전체 파이프라인을 실행합니다. 비용이 들기 전에 설치가 작동하는지 확인합니다.
워크플로우
python3 "$SKILL_DIR/scripts/ugc.py" <command> --job <job folder>로 명령을 실행하세요. 모든 유료 결과는 작업의 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초 이내에 후크(hook) 포함
- 짧은 구어체 문장
- 세그먼트당 하나의 아이디어
- 부드러운 클릭 유도 문구(CTA)
모든 HIGH 클레임을 수정하고 사용자의 의도를 유지하세요. 길이는 초당 약 2.5단어이므로 20초는 약 50단어, 60초는 약 150단어입니다. 힌디어의 경우 TTS 발음이 훨씬 좋기 때문에 say를 데바나가리 문자로 작성하세요(영어 브랜드 단어는 라틴 문자로 유지 가능). 사용자가 힝글리시 자막을 원하면 로마자 caption을 함께 넣으세요.
3. 계획
plan.yaml을 편집하세요. 필드 참조는 references/plan-reference.md에, 전체 작업 예제는 templates/plan.example.yaml에 있습니다. 현실감 있게 만드는 요소 (references/realism-playbook.md에 자세히):
- 한 집에서 2-3개의 설정 (예: 소파 미디엄, 소파 클로즈업, 주방 제품). 프로덕션이 아니라 한 사람이 몇 번의 테이크를 촬영하는 것처럼 보여야 합니다.
- 토크 세그먼트 2-8초. 동일한 설정의 연속 세그먼트는 자동 점프컷 확대/축소가 적용됩니다.
- 토크 세그먼트 2-3개마다 B-roll 1개: 손으로 따르기, 카운터 위 제품, 아침 산책. B-roll은 컷을 숨기고 제품을 적절히 보여줍니다. 제품 클로즈업에는
with_person: false를 사용하여 얼굴이 두 번 생성되지 않도록 하세요. - 제품은 최대 한 설정에서만 듭니다 (
framing: product). 사람이 제스처를 취할 때 제품이 왜곡될 수 있으므로 B-roll과 엔드 카드가 제품을 보여주도록 하세요. - 각 세그먼트에 짧은
performance큐를 제공하여 대사의 감정과 일치시키세요. - 마지막은 엔드 카드. 실제 제품 사진과 실제 로고가 합성되므로 라벨이 항상 올바릅니다.
- 음성.
references/script-and-voice.md로 선택하세요. fal의 기본 음성은 대부분 미국식 또는 영국식입니다. 인도 억양의 경우 ElevenLabs Voice Library의 인도 음성과 함께provider: elevenlabs를 사용하거나 실제 녹음과 함께provider: file을 사용하세요(가장 현실적인 옵션).
그런 다음 validate(모든 오류 수정)와 estimate를 실행하세요.
체크포인트 1. 다음을 포함하는 메시지 하나를 보내세요:
- 세그먼트 테이블 (id, shot, setup, line)
- 플래그가 지정된 클레임과 변경한 내용
- 음성 선택
- 각 설정을 한 줄씩
- 예상 길이와 비용
"진행"을 묻고 사용자가 확인할 때까지 계속하지 마세요.
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 Act / ASCI 클레임 규칙, 안전한 표현 테이블.check가 무언가 플래그를 지정할 때 읽으세요.references/plan-reference.md: 모든plan.yaml필드.references/models-and-costs.md: 각 모델의 역할, 가격, 최신 모델로 교체하는 방법.references/troubleshooting.md: 설치, 키, 네트워크 허용 목록, API 오류, 수정 방법.