imajin-diffusion Service

AI diffusion model image generation with multi-model support, layout presets, and async job management.

Overview

Property	Value
Port	8002 (default), 41227 (desktop)
Stack	Python, FastAPI, PyTorch, diffusers
Package	`@lilith/imajin-diffusion-client`

Architecture

imajin-diffusion/
├── service/           # Python FastAPI backend
│   └── src/
│       ├── api/       # FastAPI routes
│       ├── jobs/      # Async job management
│       └── config/    # Settings
├── types/             # @lilith/imajin-diffusion-types
└── client/            # @lilith/imajin-diffusion-client

API Endpoints

Endpoint	Method	Description
`/health`	GET	GPU status, model availability
`/models`	GET	List available diffusion models
`/layouts`	GET	List layout presets
`/generate`	POST	Synchronous generation
`/generate/async`	POST	Start async job
`/generate/batch`	POST	Batch generation
`/jobs/{id}`	GET	Job status
`/jobs/{id}/result`	GET	Job result (image)
`/jobs/{id}`	DELETE	Cancel/delete job

Full API documentation: imajin-diffusion/README.md

Models

Model ID	Name	Use Case
`photorealistic`	Juggernaut XL v9	Product photography, realistic images
`anime`	Animagine XL 3.1	Stylized, anime-style images

Layout Presets

Layout	Dimensions	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

Generation Options

interface GenerateRequest {
  prompt: string;
  negativePrompt?: string;
  model?: 'photorealistic' | 'anime';
  layout?: LayoutType;
  width?: number;
  height?: number;
  steps?: number;           // 1-50, default 30
  guidanceScale?: number;   // 1-20, default 7.5
  seed?: number;            // For reproducibility
  enableTextOverlay?: boolean;
  textSpans?: TextSpan[];
  enableWatermark?: boolean;
  enableModeration?: boolean;
}

Client Usage

import { ImageGenerationClient } from '@lilith/imajin-diffusion-client';

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

// Synchronous generation (small images)
const result = await client.generate({
  prompt: 'Professional product photo of a t-shirt',
  model: 'photorealistic',
  layout: 'product_square',
});

// Async generation (large images)
const { jobId } = await client.generateAsync({
  prompt: 'Wide hero banner',
  layout: 'hero',
});
const result = await client.pollJobStatus(jobId);

// Smart generation (auto-selects sync/async)
const result = await client.generateSmart({
  prompt: 'Any image',
  layout: 'widescreen',
});

GPU Configuration

IMAGE_GEN_PHOTOREALISTIC_DEVICE=cuda:0
IMAGE_GEN_ANIME_DEVICE=cuda:1

Models can be assigned to different GPUs for parallel processing.

Desktop Integration

For Electron/desktop integration patterns, see INTEGRATION.md.

3.5 KiB Raw Blame History