/viral-content-factory

Viral Content Factory

End-to-end system for generating viral TikTok/Instagram content promoting a product through AI-generated characters. Creates two content types:

1. Carousels — sets of 7-8 styled images per topic (Gemini image generation)
2. Mannequin videos — outfit-change animations using morph suit figures (Gemini + Kling 3)

Shared tools

The repo's tools/ CLIs wrap the paid generation steps so they can be scripted per frame/slide with a uniform JSON envelope:

Keys: GEMINI_API_KEY, FAL_KEY. render_video.py needs Node.js 18+. Full map + flags in tools/README.md.

Phase 0: Gather Requirements

Before generating anything, collect this information from the user:

Required

1. Product — What app/product are we promoting? What does it do? What's the price?
2. Characters — Who are the AI personas? For each character:
   • Name and handle (@)
   • Visual description (age, ethnicity, build, hair, style aesthetic)
   • Voice/personality (how they talk, what makes them unique)
   • Content themes that work for them
3. Reference images — Ask user to provide:
   • Style reference images (Pinterest, TikTok screenshots) in an ideas/ folder
   • Character reference photos if they exist
4. API keys — Check for:
   • Gemini API key (for image generation)
   • fal.ai API key (for Kling video generation)
5. Existing content — Check what's already been generated to continue numbering

Optional

• Aspect ratio preference (4:5 for carousels, 9:16 for videos)
• Specific themes or viral hooks the user wants
• Brand guidelines (colors, typography, tone)

Phase 1: Character Creation

When creating new characters, design them to be:

• Visually distinctive — recognizable across all content
• Personality-driven — each has a unique voice and perspective
• Meme-worthy — something about them is shareable (a cat giving fashion advice, a 65yo who dresses better than everyone)
• Relatable — viewers see themselves or aspire to be like them

Character Archetypes That Work

Character Template

CHARACTER_NAME = (
    "[Physical description — age, ethnicity, build, hair, distinguishing features] "
    "[Style aesthetic — what fashion world they live in] "
    "[Energy/vibe — how they carry themselves] "
)

STYLE = (
    "PHOTO STYLE: REAL iPhone photo — [specific setting and lighting]. "
    "NOT a studio shot. NOT AI-looking. [Platform reference]. "
    "IMPORTANT: NO AI artifacts — no extra fingers, no weird hands, no garbled text. "
    "[Aspect ratio]. "
)

TEXT = (
    "TEXT OVERLAY: Simple white text, clean sans-serif font. "
    "Subtle shadow for readability. [Position]. "
    "Plain white text, casual lowercase. MUST be spelled correctly. "
)

ONE_IMAGE = (
    "CRITICAL: Generate exactly ONE single image, not a collage or grid. "
    "NO AI artifacts — realistic hands with 5 fingers, natural proportions. "
)

Phase 2: Carousel Generation

Folder Structure

project_root/
├── .venv/                    # Python venv with google-genai, Pillow, fal-client
├── ideas/                    # Reference images (Pinterest saves, screenshots)
├── old/                      # Archive of previous batches
├── character_name/
│   ├── generate_name_XX_YY.py   # Generator script
│   ├── reference_photo.jpeg     # Character reference image
│   ├── old/                     # Previous carousels
│   ├── XX_carousel_name/        # Output folder
│   │   ├── slide_01.png
│   │   └── ...
│   └── ...

Generator Script Pattern

Every generator script follows this exact structure:

#!/usr/bin/env python3
import io, os, time
from pathlib import Path
from PIL import Image
from google import genai
from google.genai import types

API_KEY = os.environ["GEMINI_API_KEY"]
MODEL = "gemini-3-pro-image-preview"
W, H = 1080, 1350  # 4:5 for carousels, 1080x1920 for 9:16 video frames
ASPECT = "4:5"      # or "9:16"

BASE = Path(__file__).parent
CLIENT = genai.Client(api_key=API_KEY)

Key Functions

• gen(prompt, ref_images, retries=3) — calls Gemini, returns PIL Image
• save(img, folder, num) — resizes + saves as slide_XX.png
• gen_native(prompt, refs) — wraps gen() with ONE_IMAGE + STYLE + TEXT constants
• load_refs() — loads character reference photos + idea images
• generate_carousel(key, data) — iterates slides, calls gen_native, saves

Style Types

Native influencer style (for character accounts):

• Real iPhone photo aesthetic, NOT studio
• Natural lighting, warm tones, casual composition
• White text overlay, lowercase, sans-serif, Instagram stories style
• ONE image per generation (no grids/collages)
• Anti-artifact prompt: "NO AI artifacts — no extra fingers, no weird hands, no garbled text"

Editorial brand style (for brand accounts):

• Warm beige/cream background (#F5F0E8)
• Product cutouts on neutral bg, flatlay catalog style
• Bold serif titles + clean sans-serif body text
• ✓/✗ for do/don't comparisons
• Pinterest-save-worthy infographic feel

Pet character style (for animal accounts):

• Real iPhone photo by pet owner
• Animal always dignified, unbothered, slightly judgy
• Same cozy apartment background
• Humor comes from pet's "opinion" on the topic

Carousel Data Structure

Each carousel is defined in a CAROUSELS dict:

CAROUSELS = {
    "XX_carousel_name": {
        "title": "hook title for the carousel",
        "slides": [
            f"{CHARACTER}COVER: [description]. White text: '[hook]'. Lowercase.",
            f"{CHARACTER}[Slide 2 description]. White text: '[caption]'.",
            # ... 5 more content slides
            f"{CHARACTER}[Last slide — subtle {{brand}} mention]. White text: '[{{brand}} plug]'. Lowercase.",
        ],
    },
    # ... more carousels
}

Running Generation

cd project_root
.venv/bin/python character_name/generate_name_XX_YY.py

Multiple scripts can run in parallel (they share the Gemini API). Expect ~3-5 minutes per carousel (7 slides).

Moving Old Content

Before generating new batches, move existing carousels to old/:

mkdir -p character_name/old
for d in character_name/[0-9]*; do [ -d "$d" ] && mv "$d" character_name/old/; done

Phase 3: Mannequin Video Generation

Concept

A person in a black full-body morph suit (zentai/spandex) gets "dressed" in different outfits. Each outfit is a separate frame, then animated with Kling 3 via fal.ai.

Step 1: Generate Frames (Gemini)

Anchor-first approach for consistent background:

1. Generate frame_00_anchor — morph suit person, clean room, no clothes
2. For ALL other frames, feed anchor as input + prompt "change only the outfit"

Key prompt for redressing:

REDRESS = (
    "Take this exact image — same room, same wall, same floor, same lighting, "
    "same camera angle, same body shape, same person. "
    "CRITICALLY IMPORTANT: The person MUST remain a FACELESS figure in a BLACK MORPH SUIT. "
    "HEAD covered in BLACK FABRIC — NO face, NO eyes, NO skin, NO hair visible. "
    "HANDS in BLACK GLOVES. ALL skin covered in black lycra. "
    "Do NOT turn them into a real person. Do NOT add a face. "
    "ONLY change the outfit ON TOP of the black morph suit. "
    "Dress them in: "
)

Common issues and fixes:

• Gemini removes morph suit → add stronger "MUST remain faceless" language
• Background changes → always feed anchor frame as reference
• Body shape changes → emphasize "same body shape" in prompt
• Outfit previews leak from references → add "NO sketches on wall" when not wanted

Step 2: Animate Frames (Kling 3 via fal.ai)

import fal_client
os.environ["FAL_KEY"] = "<fal-api-key>"

# Upload frame
image_url = fal_client.upload_file(frame_path)

# Generate 5s video clip
result = fal_client.subscribe(
    "fal-ai/kling-video/v2/master/image-to-video",
    arguments={
        "prompt": "A faceless person in a black morph suit wearing [outfit] ...",
        "image_url": image_url,
        "duration": "5",
        "aspect_ratio": "9:16",
    },
    with_logs=True,
)
video_url = result["video"]["url"]

Step 3: Trim and Concatenate

# Trim each clip to desired duration
ffmpeg -y -i clip.mp4 -t 1.5 -c:v libx264 -preset fast -crf 18 -r 30 -pix_fmt yuv420p -an trimmed.mp4

# Concatenate all clips
ffmpeg -y -f concat -safe 0 -i clips.txt -c copy final.mp4

Timing guide:

• First "before" clip: 3-5s (longer, establish the cringe)
• Each "after" outfit: 1-2s (quick cuts, satisfying transitions)
• Total target: 10-15s + app demo at the end

Step 4: Add Text and Demo

After generating the raw video, add in a video editor:

• Text overlay: "my style 1 year ago vs..." → "my style now"
• App demo screen recording at the end: "I used this app to find my style"

Phase 4: Quality Control

Anti-Artifact Checklist

Before approving frames, check for:

• Extra fingers or malformed hands
• Garbled/repeated text in overlays
• Inconsistent background between frames
• Morph suit removed (face/skin visible)
• Body shape changed between frames
• Unnatural proportions or poses
• Items floating or disconnected from body

If artifacts found: regenerate the specific frame with stronger anti-artifact prompts. Don't regenerate the whole batch.

Viral Hook Library

Bait & Switch

• "the app i've been using for 40 years" (reveal: it's her brain)
• "this $15 trick changed my entire wardrobe" (reveal: tailoring)
• "the outfit that got me fired" (reveal: she looked too good)

Revenge/Ex Energy

• "my ex invited me to his wedding. this is what i wore"
• "my ex texted 3 minutes after i posted this fit"
• "outfits i wore to run into my ex 'accidentally'"
• "dressed for my ex's wedding like i won the breakup"

Bold/Savage

• "i'm 65 and i dress better than your girlfriend. sorry"
• "my granddaughter asked me to stop dressing like this"
• "outfits that got me in trouble"
• "outfits that got me free drinks"
• "stole every look at the party and didn't even try"

Transformation

• "{month year} vs now — same closet, different person"
• "same body, different outfit, different person"
• "how she went from 'cute' to 'WHO IS SHE'"
• "my style 1 year ago vs now (he finally proposed)"
• "your closet before vs after"

Practical/Save-Worthy

• "your jeans can make you look taller — 4 tips"
• "the fabric cheat sheet that saves money"
• "4 shoes that go with literally everything"
• "the tuck that changes everything"
• "what shoes to wear with each skirt"

Rating/Judgment

• "{pet name} rates your shoe collection"
• "girls rated my outfits 1-10"
• "rate my fit — spring edition"
• "outfits i judged 6 months ago — i was right"

Nostalgia/Comparison

• "at 25 i chased trends. at 65 i chase quality"
• "how my style evolved: 25, 45, 65"
• "dressed like my dad in 1995 vs me in 2026"
• "what i stopped wearing (not because of age)"

Challenge/Formula

• "one hoodie, five fits"
• "1 blazer, 5 outfits"
• "7 days, 7 looks from 12 pieces"
• "one scarf, six ways"
• "10 spring essentials — the checklist"

Humor/Pet

• "pov: your cat has better style than you"
• "{pet name} was banned from fashion week"
• "{pet name}'s dating profile"
• "outfits my cat approved (and he was right)"
• "{pet name} stole my date"

Hook Rules

1. First 3 words decide everything — front-load the intrigue
2. Personal > general — "my ex" beats "how to style"
3. Numbers perform — "5 outfits", "4 tips", "$87 total"
4. Conflict hooks — "vs", "but", "stopped", "never again"
5. Emotion hooks — revenge, jealousy, surprise, aspiration
6. Always lowercase — casual energy, not corporate
7. End with a {brand} plug — natural, conversational, not ad-like

Quick Reference

Dependencies

pip install google-genai Pillow fal-client
# Also needs: ffmpeg (for video concat)

API Keys

• Gemini: from environment / project .env files
• fal.ai: from environment / project .env files
• Never commit keys to git