Vansaar UGC-Video
Gesichtsfoto + Produktfoto + Drehbuch → ein 9:16, 1080×1920, 30 fps MP4, das aussieht, als hätte ein indischer Kunde über 45 es zu Hause mit dem Handy gefilmt. Claude ist der Regisseur: Es schreibt den Plan, prüft Behauptungen, begutachtet alle Bilder und steuert eine eingebaute Python-Engine (scripts/ugc.py), die KI-Modelle auf fal.ai aufruft und das Ergebnis mit ffmpeg bearbeitet.
Drehbuch ─► Sprache (ElevenLabs) ─► Wortzeiten ─► Pausen gestrafft ─► ein Audio-Slice pro Einstellung
Gesicht+Produkt ─► Keyframes (Nano Banana Pro) ─► Sprechclips (OmniHuman 1.5) / B-Roll (Kling 3)
alles ─► Jump-Cut-Schnitt + Handkamera-Drift + Handy-Grade/Körnung + Handy-Mikro-Audio
─► Untertitel + KI-Label + Endcard (echtes Produktfoto) ─► QA ─► final.mp4
Grundregeln
Diese schützen die Marke und die Personen im Video. Erkläre sie dem Benutzer, wenn sie auftauchen; lehne nicht einfach ab.
- Das Gesicht muss nutzbar sein. Es sollte ein KI-generierter Charakter oder eine reale Person sein, die schriftlich die Erlaubnis zur Nutzung ihres Abbilds in Anzeigen gegeben hat. Niemals ein Prominenter, Influencer, Arzt oder eine öffentliche Person, und niemals jemand, der ohne Zustimmung fotografiert wurde. Wenn du dir nicht sicher bist, wo das Gesicht herkommt, frage einmal nach.
- Behalte das „KI-generiert“-Label bei. Es ist standardmäßig aktiviert, als kleines Label oben. Die ASCI-Richtlinien für virtuelle Influencer und die KI-Inhaltsregeln der Plattformen erwarten es. „Realistisch“ bedeutet gute Handwerkskunst, nicht die Täuschung von Zuschauern. Wenn der Benutzer es entfernen möchte, erkläre ihm, was die Regeln erwarten und überlasse die Entscheidung dem Compliance-Verantwortlichen (
disclosure.show: false). - Behauptungen müssen sicher sein. Ayurvedische Produkte unterliegen dem Drugs & Magic Remedies Act und den ASCI-Regeln für Gesundheitsbehauptungen. Bevor etwas generiert wird, führe
checkaus, schreibe dann jede HOHE Markierung um und markiere jede MITTLERE für den Benutzer. Der KI-Charakter darf niemals eigene gesundheitliche Ergebnisse beschreiben („mein Zucker ist gesunken“): das ist ein erfundenes Testimonial. Er kann über Routine, Zutaten, Geschmack und einfache Anwendung sprechen. Details sind inreferences/compliance-india.md. - Geld fließt erst nach einem „Go“. Sprache und Keyframes kosten Cents; Sprechclips kosten Dollar. Halte an beiden untenstehenden Checkpoints an und zeige die Kosten vor jeder kostenpflichtigen Phase an.
- Bitte den Benutzer niemals, einen API-Key in den Chat einzufügen. Verweise auf die Einrichtungsschritte (
.env-Datei,setkeyin seinem eigenen Terminal oder seine Umgebungseinstellungen).
Einrichtung (einmal pro Maschine / Sitzung)
SKILL_DIR ist der Ordner, der diese Datei enthält. Aufträge werden in einen Ordner gelegt, den der Benutzer öffnen kann: In Claude Code verwende ./ugc_jobs/<slug> im aktuellen Projekt; in einem claude.ai-Chat verwende /mnt/user-data/outputs/ugc/<slug>.
pip install -r "$SKILL_DIR/requirements.txt" # füge --break-system-packages hinzu, falls pip sich weigert
python3 "$SKILL_DIR/scripts/ugc.py" doctor # prüft Python-Bibliotheken, ffmpeg+libass, Schriftarten, Key, Netzwerk
- Kein fal.ai-Key. Sage dem Benutzer, er solle einen auf fal.ai erstellen (Dashboard → Keys) und Guthaben hinzufügen (US$10-20 reichen für ein paar Videos). Dann speichert er ihn selbst auf eine von drei Arten: eine
.env-Datei mitFAL_KEY=...im Ordner, in dem Claude läuft; Ausführen vonpython3 scripts/ugc.py setkeyin seinem eigenen Terminal; oder in einer Cloud-Sitzung eine UmgebungsvariableFAL_KEYin den Umgebungseinstellungen. - Netzwerk blockiert („doctor“ zeigt „cannot reach fal.ai“). Die Sandbox muss
queue.fal.run,rest.fal.ai,*.fal.mediaundstorage.googleapis.comerlauben, plusapi.elevenlabs.iofür die direkte Sprachoption. Sage dem Benutzer genau das. Wo er das ändern kann, steht inreferences/troubleshooting.md. - ffmpeg fehlt. Siehe
references/troubleshooting.md. - Kostenlos testen.
python3 "$SKILL_DIR/scripts/ugc.py" demo --out <ordner>führt die gesamte Pipeline mit Offline-Ersatz (--mock) aus. So kann die Installation vor dem Geldausgeben getestet werden.
Arbeitsablauf
Führe Befehle als python3 "$SKILL_DIR/scripts/ugc.py" <befehl> --job <auftragsordner> aus. Jedes kostenpflichtige Ergebnis wird im state.json des Auftrags zwischengespeichert. Das erneute Ausführen eines Befehls führt nie zu doppelter Bezahlung für dieselbe Eingabe, und eine unterbrochene Anfrage wird beim nächsten Lauf fortgesetzt.
1. Aufnahme
Du benötigst drei Eingaben: das Gesichtsbild, das Produktbild und das Drehbuch. Frage in einer Nachricht nach allem Fehlenden, plus allem, was du nicht ableiten kannst:
- Sprache: Englisch oder Hindi/Hinglish
- der genaue Produktname
- Ziellänge (Standard: was das Drehbuch natürlich benötigt, innerhalb von 20-60 s)
- das Geschlecht der Person oder Sprachpräferenz
- jede Umgebungspräferenz (Standard: eine sonnige indische Wohnung)
Bestätige hier die Gesichtseinwilligung, wenn sie unklar ist.
Dann betrachte beide Bilder selbst:
- Gesicht. Schreibe
character.description: ungefähres Alter, Haare, Hautton, auffällige Merkmale und Kleidung. Das verstärkt die Identität in jedem Prompt. Wenn das Foto niedrig aufgelöst ist, seitlich oder von Sonnenbrille, Händen oder Maske verdeckt wird, bitte um ein klares Vorderansichtsfoto, da die Lippensynchronisation davon abhängt. - Produkt. Überprüfe, ob das Etikett lesbar ist. Notiere, ob der Hintergrund einfarbig weiß oder transparent ist (die Endcard kann es ausschneiden) oder unruhig (die Endcard zeigt es als Karte). Wenn der Benutzer ein transparentes PNG-Packshot hat, frage danach.
2. Drehbuchdurchlauf
Führe init mit --face, --product, --script (oder --text), --lang, --title und --product-name aus. Dann führe check --job <auftrag> aus.
Schreibe das Drehbuch mit references/script-and-voice.md für gesprochenes UGC um:
- ein Hook in den ersten 2 Sekunden
- kurze gesprochene Sätze
- eine Idee pro Abschnitt
- ein sanfter Call-to-Action
Behebe jede HOHE Behauptung und behalte die Bedeutung des Benutzers bei. Die Länge beträgt etwa 2,5 Wörter pro Sekunde, also 20 s entsprechen etwa 50 Wörter und 60 s etwa 150. Für Hindi schreibe say in Devanagari (englische Markenwörter können in lateinischer Schrift bleiben), da TTS es weitaus besser ausspricht. Füge eine caption in römischer Schrift hinzu, wenn der Benutzer Hinglish-Untertitel wünscht.
3. Plan
Bearbeite plan.yaml. Die Feldreferenz ist references/plan-reference.md; ein vollständiges durchgearbeitetes Beispiel ist templates/plan.example.yaml. Was es realistisch macht (Details in references/realism-playbook.md):
- 2-3 Aufbauten in einem Zuhause (z.B. Sofa weit, Sofa nah, Küche Produkt). Es sollte aussehen, als ob eine Person ein paar Takes filmt, nicht wie eine Produktion.
- Sprechsegmente von 2-8 s. Aufeinanderfolgende Segmente mit demselben Aufbau erhalten automatische Jump-Cut-Heranzoomungen.
- Ein B-Roll alle 2-3 Sprechsegmente: Hände beim Eingießen, Produkt auf der Arbeitsplatte, Morgenlauf. B-Roll versteckt Schnitte und zeigt das Produkt richtig. Verwende
with_person: falsefür Produktnahaufnahmen, damit Gesichter nicht doppelt generiert werden. - Das Produkt wird höchstens in einem Aufbau gehalten (
framing: product). Produkte können sich verziehen, während Menschen gestikulieren, also lass B-Roll und die Endcard das Produkt tragen. - Gib jedem Segment einen kurzen
performance-Hinweis, der zur Emotion der Zeile passt. - Endcard zuletzt. Das echte Produktfoto und das echte Logo werden dort eingefügt, daher ist das Etikett immer korrekt.
- Sprache. Wähle sie mit
references/script-and-voice.md. Die voreingestellten Stimmen von fal sind meist amerikanisch oder britisch. Für einen indischen Akzent verwendeprovider: elevenlabsmit einer indischen Stimme aus der ElevenLabs Voice Library oderprovider: filemit einer echten Aufnahme (die realistischste Option überhaupt).
Dann führe validate aus (behebe alle Fehler) und estimate.
CHECKPOINT 1. Sende eine Nachricht mit:
- der Segmenttabelle (Id, Einstellung, Aufbau, Zeile)
- den Behauptungen, die markiert wurden und was du geändert hast
- der Auswahl der Stimme
- den Aufbauten in je einer Zeile
- der geschätzten Länge und den Kosten
Frage „Go?“ und fahre nicht fort, bis der Benutzer zustimmt.
4. Sprache und Keyframes (günstig)
Führe voice aus. Lies die Längentabelle. Wenn eine Warnung „Transkript stimmt nur zu N% überein“ erscheint, hat die TTS Wörter falsch ausgesprochen oder übersprungen: Schreibe diese Zeile um (schreibe Zahlen aus, verwende Devanagari) und führe voice --only <id> --force aus. Wenn die Gesamtlänge außerhalb von 20-60 s liegt, kürze das Drehbuch oder passe voice.speed an (0,9-1,15).
Führe frames aus, öffne dann work/frames/contact.jpg und die vollgroßen Kandidaten in work/frames/<schlüssel>/. Überprüfe jeden anhand der Keyframe-Checkliste in references/realism-playbook.md: Identität stimmt mit dem Gesichtsfoto überein, natürliche Haut, korrekte Hände, das Produktetikett stimmt mit dem Produktfoto überein, ein echtes Zuhause, Handykamera-Licht. Setze pick: auf den besten Kandidaten. Wenn keiner besteht, schärfe die Szene oder Beschreibung und führe frames --only <aufbau> --force aus. Mache höchstens 2 Runden pro Aufbau, zeige dem Benutzer dann, was falsch ist.
CHECKPOINT 2. Sende work/voice/vo_preview.mp3 und das Kontaktblatt, sage, welche Kandidaten du ausgewählt hast und warum, und nenne die Kosten für die Sprechclips (der teure Teil). Warte auf OK. Die Stimme später zu ändern, bedeutet, die Sprechclips neu zu machen.
5. Clips
Führe clips aus. Sprechclips dauern etwa 1-5 Minuten pro Stück und laufen gleichzeitig. Wenn einer fehlschlägt, bleiben die anderen erhalten, also führe clips erneut aus, um nur die Fehlgeschlagenen zu wiederholen. Stelle sicher, dass keine Warnung besagt, dass ein Clip kürzer als sein Audio ist.
6. Zusammenbau und QA
Führe assemble, dann qa aus. Öffne out/<slug>_contact.jpg und überprüfe:
- kein Gesichts-Drift zwischen Schnitten
- keine verzogenen Hände oder Produkte
- Untertitel verdecken nicht den Mund oder das Produktetikett
- der Endcard-Text ist lesbar
Wenn ein Clip schlecht ist, führe clips --only <id> --force aus, dann assemble erneut. Behebe jeden FEHLER, den die QA meldet; untersuche jede PRÜFUNG.
7. Ausliefern
Sende out/<slug>.mp4 (und das Kontaktblatt, falls nützlich). Gib in 3-5 Zeilen:
- Länge und geschätzte Kosten (
state.jsonführt den laufenden Gesamtbetrag) - jede Behauptung, die der Benutzer noch von seinem Compliance-Verantwortlichen genehmigen lassen muss
- dass das KI-Label aktiviert ist
- die ein oder zwei Anpassungen, die das nächste Video am wahrscheinlichsten verbessern
Um auch eine untertitelfreie Kopie für Redakteure zu erstellen, setze captions.clean_copy: true.
Kurzreparaturen
| Symptom | Lösung |
|---|---|
| Gesicht sieht nicht wie das Foto aus | reichere character.description, candidates: 3, ein klareres Vorderansichts-Quellfoto |
| Plastik- oder Beauty-Filter-Haut | neu generieren; vermeide „schön/makellos“ in Szenen; behalte grain ≥ 0,4 |
| Verzerrtes Produktetikett | generiere diesen Keyframe neu oder entferne das Produkt aus Sprechaufbauten (Endcard + B-Roll tragen es) |
| Lippen driften oder Mund verschmiert | kürzeres Segment (≤ 6 s), frontaler Keyframe mit sichtbarem Mund, versuche das Kling Avatar-Modell in config/models.yaml |
| Roboterhafte Stimme | senke stability (0,35-0,45), Kommata für Atempausen, eine echte Aufnahme oder das eleven-v3-Modell |
| Zu langsam / zu lang | finish.tighten_pauses: 0,22, voice.speed: 1,08, Wörter kürzen |
| B-Roll wirkt unecht | einfachere Bewegung (eine Aktion), with_person: false oder motion: kenburns auf einem guten Standbild |
Mehr in references/troubleshooting.md.
Referenzdateien (bei Bedarf lesen)
references/realism-playbook.md: was KI-UGC realistisch wirken lässt; Checklisten für die Überprüfung von Keyframes und Endvideos. Vor der Planung von Aufbauten und bei der Begutachtung von Bildern lesen.references/script-and-voice.md: UGC-Drehbuchstruktur für ein indisches Publikum über 45, Schreiben für TTS (Hindi/Hinglish), Auswahl und Anpassung von Stimmen, Beispielskripte.references/compliance-india.md: Zustimmung zum Abbild, KI-Offenlegung, DMR-Gesetz/ASCI-Anspruchsregeln, eine Tabelle mit sicheren Formulierungen. Lesen, wennchecketwas markiert.references/plan-reference.md: jedesplan.yaml-Feld.references/models-and-costs.md: welches Modell was tut, Preise, wie man neuere Modelle einwechselt.references/troubleshooting.md: Installation, Keys, Netzwerk-Allowlists, API-Fehler, Lösungen.