BrandSafe AI

The Anti-Hallucination Ad Generator - Brand-safe creative generation with deterministic logo compositing.

🛡️ Brand-Safe Architecture

BrandSafe AI uses a Hybrid Guardian approach where:

• AI generates: Background textures/images ONLY
• Deterministic code handles: Logo placement, text rendering, safe zones
• AI NEVER draws: Logos, brand elements, or text (prevents hallucination)

This guarantees 100% logo integrity and text accuracy in all generated ads.

🎯 Two Generation Modes

1. Reference Edit Mode (Remix)

Upload an existing ad creative that already contains logo + text. The system:

1. Uses AI to change ONLY the background and people
2. Applies Zone-Lock Overlay to preserve original logo/text pixel-perfect
3. Returns the edited image with branding intact

Original Ad → AI edits background → Zone-lock restores branding → Final

2. New Image Mode (Creator)

Generate a brand-new creative from scratch:

1. AI generates a background-only image (no logos, no text)
2. Optional: AI generates copy (headlines, CTAs) via text model
3. Compositor places logo + headline + CTA using template zones
4. Returns a professionally composed ad

AI Background → Compositor adds logo → Compositor adds text → Final

🚀 Quick Start

Prerequisites

• Python 3.12+
• Node.js 18+
• pnpm
• Supabase account
• Clerk account
• Google Gemini API key

Environment Variables

Backend (backend/.env):

# Supabase
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Gemini AI
GEMINI_API_KEY=your_gemini_api_key

# Clerk
CLERK_SECRET_KEY=your_clerk_secret

# App
DEBUG=true
ENVIRONMENT=development

Frontend (frontend/.env.local):

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key

Running the App

Terminal 1 - Backend:

cd backend
source venv/bin/activate  # or: . venv/bin/activate
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Terminal 2 - Frontend:

cd frontend
pnpm dev

Open browser:

http://localhost:3000

🔧 API Endpoints

Variations API

REMIX Mode - Edit reference image:

POST /api/variations/generate-upload
Content-Type: multipart/form-data

brand_id: string (required)
instruction: string (required)
reference_image: File (required)
lock_zones: boolean (default: true)
replace_copy: boolean (default: false)
model_pref: "pro" | "flash" (default: "pro")
template_ids: string (comma-separated)
count: number (default: 4)
hook_angles: string (comma-separated)
visual_style: string

CREATOR Mode - New ad from scratch:

POST /api/variations/create
Content-Type: application/json

{
  "brand_id": "uuid",
  "instruction": "Professional lifestyle background",
  "headline": "Transform Today",
  "subheadline": "Optional subtext",
  "cta_text": "Shop Now",
  "template_ids": ["instagram_story", "instagram_square"],
  "count": 4,
  "hook_angles": ["benefit_led", "social_proof", "urgency"],
  "visual_style": "lifestyle",
  "generate_copy": true,
  "model_pref": "pro"
}

🤖 AI Models

Image Generation

• Pro (default): gemini-3-pro-image-preview - Higher quality, 2K output
• Flash (fallback): gemini-2.5-flash-image - Faster, good quality

The system automatically falls back to Flash if Pro fails.

Copy Generation

• Model: gemini-2.5-pro-preview-05-06 - Text generation for headlines/CTAs

📐 Template System

Templates define zones for professional ad composition:

Template	Platform	Dimensions	Aspect
instagram_story	Instagram	1080×1920	9:16
instagram_square	Instagram	1080×1080	1:1
facebook_feed	Facebook	1200×628	1.91:1
google_300x250	Google	300×250	-
google_300x600	Google	300×600	-
tiktok_standard	TikTok	1080×1920	9:16

Each template defines zones for:

• Logo - Fixed position, deterministic placement
• Headline - Auto-sizing typography
• Subheadline - Supporting text
• CTA - Styled button
• Product - Product image area (optional)

🎨 Diversification (Andromeda/Gen+ Compliance)

The system ensures distinct variations across:

• Hook Angles: benefit_led, social_proof, urgency, problem_solution, curiosity, question
• Visual Styles: lifestyle, ugc, corporate, minimal, vibrant
• Scene Keywords: outdoor, indoor, urban, professional, active, social

Diversity scoring prevents near-duplicate outputs.

🔒 Zone-Lock System

For reference edits, the Zone-Lock system:

1. Identifies protected zones from the template (logo, headline, CTA)
2. Allows AI to edit only unprotected areas (background, people)
3. Copies protected pixels from original onto edited output
4. Uses feathered edges for seamless blending

This guarantees logos and text remain pixel-identical.

📁 Project Structure

brandsafe/
├── backend/
│   ├── app/
│   │   ├── api/routes/       # API endpoints
│   │   ├── services/         # Core services
│   │   │   ├── gemini_backgrounds.py   # Background-only generation
│   │   │   ├── zone_lock.py            # Zone preservation
│   │   │   ├── copy_generator.py       # AI copy generation
│   │   │   ├── compositor_v2.py        # Deterministic compositing
│   │   │   ├── creative_synth.py       # Main generation engine
│   │   │   └── diversity_scorer.py     # Pack diversity
│   │   ├── templates/        # Ad template definitions
│   │   └── config.py         # Settings
│   └── fonts/                # Typography
├── frontend/
│   ├── src/
│   │   ├── app/              # Next.js pages
│   │   └── components/
│   │       └── studio/       # Generation UI
└── supabase/
    └── migrations/           # Database schema

🧪 Testing

Backend:

cd backend
source venv/bin/activate
pytest

Acceptance Tests:

1. ✅ Reference edit: Logo/text remain pixel-identical (zone-lock)
2. ✅ New image: No AI-drawn logos/text, compositor adds branding
3. ✅ Pro model default, Flash fallback on failure
4. ✅ Aspect ratios match template sizes
5. ✅ UI displays all variations with correct aspect ratios

📜 License

MIT

---

Built with ❤️ for brand-safe AI advertising