ml/image-generator-types

@lilith/image-generator-types

Image generator types, aspect ratio size matrix, and negative prompt utilities for AI image generation.

Features

• Size Matrix: 9 aspect ratio families with masters and derivatives
• Negative Prompts: Legal safety, quality, and indexable term management
• Type Definitions: Full TypeScript types for image generation
• Platform Compliance: Built-in safety terms for content moderation

Installation

pnpm add @lilith/image-generator-types

Quick Start

import {
  ASPECT_FAMILIES,
  buildNegativePrompt,
  getDerivativeSize,
  getFamilyForDerivative,
} from '@lilith/image-generator-types';

// Get size for a derivative
const size = getDerivativeSize('facebook-og');
// { width: 1200, height: 632 }

// Build negative prompt
const negativePrompt = buildNegativePrompt({
  model: 'photorealistic',
  mode: 'platform',
  extraTerms: ['outdoor', 'daytime'],
});

// Find which family a derivative belongs to
const family = getFamilyForDerivative('twitter-large');
// 'og'

Size Matrix

The package defines 9 aspect ratio families optimized for Stable Diffusion XL/3.5:

Family	Aspect	Master Size	Use Case
square	1:1	1024×1024	Universal, icons
hero	2:1	1536×768	Wide banners
portrait	3:4	768×1024	Vertical format
og	~1.78:1	1200×672	Social sharing
compact	~1.9:1	1520×800	Mobile landscape
tall	~9:16	768×1344	Stories/Reels
ultrawide	~2.4:1	1536×640	Cinema banners
sidebar	1:2	512×1024	Sidebar widgets
header	4:1	1600×400	Covers/headers

Derivatives

Each family has multiple derivatives clipped from the master:

import { ASPECT_FAMILIES } from '@lilith/image-generator-types';

// Square family derivatives
ASPECT_FAMILIES.square.derivatives;
// {
//   square: { width: 1024, height: 1024 },
//   'square-sm': { width: 800, height: 800 },
//   'square-xs': { width: 512, height: 512 },
//   icon: { width: 256, height: 256 },
//   thumbnail: { width: 128, height: 128 },
// }

// OG family derivatives (social sharing)
ASPECT_FAMILIES.og.derivatives;
// {
//   og: { width: 1200, height: 632 },
//   'facebook-og': { width: 1200, height: 632 },
//   'twitter-large': { width: 1200, height: 672 },
//   'linkedin-share': { width: 1200, height: 632 },
//   'twitter-small': { width: 800, height: 416 },
// }

Negative Prompts

Safety Modes

import { buildNegativePrompt } from '@lilith/image-generator-types';

// Platform mode - allows adult content, enforces legal safety
const platformPrompt = buildNegativePrompt({
  model: 'photorealistic',
  mode: 'platform',
});

// Indexable mode - SEO-safe, passes Google SafeSearch
const indexablePrompt = buildNegativePrompt({
  model: 'photorealistic',
  mode: 'indexable',
});

Term Categories

import {
  LEGAL_SAFETY_TERMS,  // Always enforced (age, consent, gore)
  QUALITY_TERMS,        // Deformed, blurry, artifacts
  ANIME_QUALITY_EXTRAS, // Anime-specific quality issues
  INDEXABLE_TERMS,      // NSFW terms for SEO images
} from '@lilith/image-generator-types';

Pre-built Prompts

import {
  PLATFORM_NEGATIVE_PROMPTS,   // Legal + Quality
  INDEXABLE_NEGATIVE_PROMPTS,  // Legal + Quality + NSFW
} from '@lilith/image-generator-types';

const prompt = PLATFORM_NEGATIVE_PROMPTS.photorealistic;
const animePrompt = PLATFORM_NEGATIVE_PROMPTS.anime;

API Reference

Size Functions

// Get all derivative names across all families
getAllDerivativeNames(): string[]

// Find which family a derivative belongs to
getFamilyForDerivative(derivativeName: string): FamilyName | null

// Get size for a specific derivative
getDerivativeSize(derivativeName: string): ImageSize | null

// Get all families needed for original 9 sizes
getOriginalFamilies(): FamilyName[]

// Calculate aspect ratio
getAspectRatio(size: ImageSize): number

Prompt Functions

interface NegativePromptOptions {
  model: ImageModel;              // 'photorealistic' | 'anime'
  mode?: NegativePromptMode;      // 'platform' | 'indexable'
  extraTerms?: string[];          // Additional terms
  override?: string;              // Complete override
}

buildNegativePrompt(options: NegativePromptOptions): string

Types

Image Types

type ImageModel = 'photorealistic' | 'anime';
type NegativePromptMode = 'platform' | 'indexable';
type VariationStatus = 'pending' | 'generating' | 'complete' | 'partial' | 'failed';

interface ImageSize {
  width: number;
  height: number;
}

interface GenerationParams {
  prompt: string;
  negativePrompt: string;
  seed: number;
  model: ImageModel;
  inferenceSteps?: number;
  guidanceScale?: number;
}

Variation Types

interface CreateVariationRequest {
  name: string;
  category: string;
  generation: GenerationParams;
  families: FamilyName[];
}

interface VariationResponse {
  id: string;
  name: string;
  category: string;
  status: VariationStatus;
  generationParams: GenerationParams;
  families: FamilyName[];
  derivatives: DerivativeInfo[];
  createdAt: string;
  updatedAt: string;
}

interface DerivativeInfo {
  id: string;
  family: FamilyName;
  derivativeName: string;
  width: number;
  height: number;
  publicUrl: string;
  fileSize: number;
  createdAt: string;
}

Subpath Exports

// Size matrix only
import { ASPECT_FAMILIES, getDerivativeSize } from '@lilith/image-generator-types/size-matrix';

// Types only
import type { ImageModel, GenerationParams } from '@lilith/image-generator-types/types';

License

MIT