imajin/services/imajin-diffusion

Image Generation Service

AI-powered image generation service with SDXL support. Provides a Python FastAPI backend and TypeScript client libraries for integration.

Architecture

image-generation/
├── service/          # Python FastAPI service (SDXL generation)
├── types/            # @lilith/image-generation-types (TypeScript types + Zod schemas)
├── client/           # @lilith/image-generation-client (HTTP client)
└── .ports.json       # Port configuration

Quick Start

Running the Service

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

Or from the monorepo root:

npm run service:dev

Using Docker

cd service
docker build -t lilith-image-generation .
docker run --gpus all -p 8002:8002 lilith-image-generation

TypeScript Client

Installation

npm install @lilith/image-generation-client

Usage

import { ImageGenerationClient } from '@lilith/image-generation-client';

const client = new ImageGenerationClient({
  baseUrl: 'http://localhost:8002',
});

// Check health
const health = await client.healthCheck();
console.log('GPU available:', health.gpuAvailable);

// Generate image
const result = await client.generate({
  prompt: 'A professional product photo of a t-shirt',
  model: 'photorealistic',
  layout: 'product_square',
});

if (result.success) {
  console.log('Image generated:', result.result.imageData);
}

Smart Generation (Auto-async)

// Automatically uses async for large images
const result = await client.generateSmart({
  prompt: 'Wide banner image of a hoodie',
  model: 'photorealistic',
  layout: 'hero',
  enableTextOverlay: true,
  textSpans: [
    { id: 'price', text: '$49.99', x: 90, y: 90, fontSize: 48 }
  ],
});

API Endpoints

Endpoint	Method	Description
/health	GET	Health check with GPU status
/models	GET	List available models
/layouts	GET	List layout presets
/generate	POST	Synchronous generation
/generate/batch	POST	Batch generation
/generate/async	POST	Start async job
/jobs/{id}	GET	Get job status
/jobs/{id}/result	GET	Get job result
/jobs/{id}	DELETE	Delete job

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
custom	Any	User-defined dimensions

Models

Model	Description	Recommended Use
photorealistic	Juggernaut XL v9	Product photography, realistic images
anime	Animagine XL 3.1	Stylized, anime-style images

Integration with Desktop Chat App

See INTEGRATION.md for Electron/desktop integration patterns.

Dependencies

Python (service)

• lilith-image-pipeline - 7-stage pipeline orchestration
• lilith-image-utils - Text overlay, watermark, quality scoring
• diffusers - SDXL generation
• torch - GPU acceleration

TypeScript (client)

• @lilith/image-generation-types - Shared type definitions
• zod - Runtime validation

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

Ports

• Default: 8002 (development/production servers)
• Desktop integration: 41227 (Electron apps use 41220+ range)

Configure via .ports.json or environment variables.