platform-codebase/features/image-generation

Image Generation Feature

AI-powered image generation service for product images and marketing assets.

Overview

This feature provides SDXL-based image generation with:

• Multiple model support (photorealistic, anime)
• Layout presets for various use cases
• Text overlay rendering
• Content moderation
• Forensic watermarking
• Quality scoring

Architecture

image-generation/
├── service/          # Python FastAPI service
│   ├── src/
│   │   ├── api/      # API endpoints
│   │   └── config/   # Configuration
│   ├── pyproject.toml
│   └── Dockerfile
├── shared/           # TypeScript shared types
│   └── src/
│       ├── types.ts  # Type definitions
│       └── schemas.ts # Zod schemas
└── README.md

Quick Start

Running Locally

cd service

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Run the service
uvicorn src.api.main:app --reload --port 8002

Using Docker

# Build
docker build -t lilith-image-generation ./service

# Run with GPU
docker run --gpus all -p 8002:8002 lilith-image-generation

API Endpoints

Health & Info

• GET /health - Health check with GPU status
• GET /models - List available models
• GET /layouts - List layout presets

Generation

• POST /generate - Generate single image
• POST /generate/batch - Generate multiple images
• POST /generate/async - Create async job

Jobs

• GET /jobs - List all jobs
• GET /jobs/{id} - Get job status
• GET /jobs/{id}/result - Get job result
• DELETE /jobs/{id} - Delete job

Usage Examples

Basic Generation

import type { GenerateRequest, GenerateResponse } from '@lilith/image-generation-shared';

const request: GenerateRequest = {
  prompt: 'A professional product photo of a t-shirt',
  model: 'photorealistic',
  layout: 'product_square',
};

const response = await fetch('http://localhost:8002/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request),
});

const result: GenerateResponse = await response.json();
if (result.success) {
  // result.result.imageData contains base64 image
}

With Text Overlay

const request: GenerateRequest = {
  prompt: 'Product photography of a hoodie',
  model: 'photorealistic',
  layout: 'product_wide',
  enableTextOverlay: true,
  textSpans: [
    {
      id: 'price',
      text: '$49.99',
      x: 90,
      y: 90,
      fontSize: 48,
      fontFamily: 'Roboto',
      color: '#ffffff',
      strokeWidth: 2,
    },
  ],
};

Layout Presets

Layout	Size	Use Case
hero	1536x768	Wide banners
sidebar	512x1536	Tall sidebars
square	1024x1024	Social media
product_square	1024x1024	Product photos
product_wide	1200x800	Product banners
widescreen	1920x1080	Full HD

Models

Model	Description	Device
photorealistic	Juggernaut XL v9	CUDA:0
anime	Animagine XL 3.1	CUDA:1

Environment Variables

IMAGE_GEN_HOST=0.0.0.0
IMAGE_GEN_PORT=8002
IMAGE_GEN_DEBUG=false
IMAGE_GEN_PHOTOREALISTIC_DEVICE=cuda:0
IMAGE_GEN_ANIME_DEVICE=cuda:1
IMAGE_GEN_MODEL_CACHE_DIR=~/.cache/sdxl-models
IMAGE_GEN_MODERATION_SERVICE_URL=http://localhost:8001
IMAGE_GEN_WATERMARK_SERVICE_URL=http://localhost:8006

Integration with Merch Store

The image generation service integrates with the merch submissions workflow:

1. User submits merch design
2. On approval, trigger product image generation
3. Generate multiple layouts (square, wide, hero)
4. Store generated images in S3
5. Update product catalog

Dependencies

Python Packages

• lilith-image-pipeline - Pipeline orchestration
• lilith-image-utils - Image processing
• lilith-ml-service-base - FastAPI patterns
• diffusers - SDXL generation
• torch - GPU acceleration

TypeScript

• Shared types in @lilith/image-generation-shared
• Zod schemas for validation