imajin/docs/development/client-libraries.md

Client Libraries

TypeScript HTTP clients for consuming @image services.

Available Clients

Package	Service	Port
@lilith/image-generation-client	image-generation	8002
@lilith/imagegen-assistant-client	imagegen-assistant	8003
@lilith/image-processing-client	image-processing	8004

Installation

npm install @lilith/image-generation-client
npm install @lilith/imagegen-assistant-client
npm install @lilith/image-processing-client

Peer dependency: zod (for runtime validation)

npm install zod

ImageGenerationClient

Setup

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

const client = new ImageGenerationClient({
  baseUrl: 'http://localhost:8002',
  // Optional: custom fetch, timeout, etc.
});

Health Check

const health = await client.healthCheck();
console.log(health.gpuAvailable);   // true
console.log(health.models);         // ['photorealistic', 'anime']

Synchronous Generation

Best for small images (< 1024x1024):

const result = await client.generate({
  prompt: 'A professional product photo',
  model: 'photorealistic',
  layout: 'product_square',
  negativePrompt: 'blurry, low quality',
});

if (result.success) {
  const imageData = result.result.imageData;  // base64
}

Async Generation

Best for large images:

// Start job
const { jobId } = await client.generateAsync({
  prompt: 'Wide banner image',
  layout: 'hero',
});

// Poll for completion
const result = await client.pollJobStatus(jobId, {
  interval: 1000,   // Poll every 1s
  timeout: 60000,   // Max 60s
});

Smart Generation

Automatically selects sync/async based on image size:

const result = await client.generateSmart({
  prompt: 'Any image',
  layout: 'widescreen',
});
// Uses async for widescreen, sync for smaller layouts

Batch Generation

const results = await client.generateBatch([
  { prompt: 'Image 1', layout: 'square' },
  { prompt: 'Image 2', layout: 'square' },
  { prompt: 'Image 3', layout: 'square' },
]);

ImagegenAssistantClient

Setup

import { ImagegenAssistantClient } from '@lilith/imagegen-assistant-client';

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

List Pipelines

const pipelines = await client.listPipelines();
// [{ id: 'skeleton-anime-girls', name: '...' }, ...]

Generate Prompts

const result = await client.generatePrompts({
  pipelineId: 'skeleton-anime-girls',
  userInput: 'Generate 5 hologram style skeletons',
});

console.log(result.prompts);
// [{ name: 'hologram_1', prompt: '...', negativePrompt: '...' }, ...]

Analyze Context

Two-stage analysis with cultural classification:

const config = await client.analyzeContext({
  category: 'escorts',
  city: 'Tokyo',
  filters: ['kawaii', 'femboy'],
});

console.log(config.model);          // 'anime'
console.log(config.maturityLevel);  // 'suggestive'
console.log(config.prompts);        // Image prompts

ImageProcessingClient

Setup

import { ImageProcessingClient } from '@lilith/image-processing-client';

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

Sanitize

const result = await client.sanitize({
  imageData: base64Image,
});

Resize

const result = await client.resize({
  imageData: base64Image,
  width: 800,
  height: 600,
  fit: 'cover',
  quality: 85,
});

Generate Derivatives

const result = await client.derivatives({
  imageData: base64Image,
  variants: [
    { name: 'large', width: 1200 },
    { name: 'medium', width: 800 },
    { name: 'thumb', width: 150 },
  ],
});

// result.variants = { large: '...', medium: '...', thumb: '...' }

Convert Format

const result = await client.convert({
  imageData: base64Image,
  format: 'webp',
  quality: 85,
});

Error Handling

All clients throw typed errors:

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

try {
  await client.generate({ ... });
} catch (error) {
  if (error instanceof ImageGenerationError) {
    console.log(error.code);     // 'GPU_OOM'
    console.log(error.message);  // 'GPU out of memory'
    console.log(error.details);  // { requested: '8GB', available: '4GB' }
  }
}

TypeScript Types

Types are exported from -types packages:

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

import type {
  AnalyzeContextRequest,
  GenerationConfig,
  ParsedPrompt,
} from '@lilith/imagegen-assistant-types';

React Integration

Use with TanStack Query:

import { useQuery, useMutation } from '@tanstack/react-query';

const client = new ImageGenerationClient({ baseUrl: '...' });

// Query
const { data: health } = useQuery({
  queryKey: ['health'],
  queryFn: () => client.healthCheck(),
});

// Mutation
const generateMutation = useMutation({
  mutationFn: (request) => client.generate(request),
});

Or use the built-in hooks from @lilith/imagen-react:

import { useImagegenAssistant } from '@lilith/imagen-react';

const { generatePrompts, isLoading } = useImagegenAssistant({
  baseUrl: 'http://localhost:8003',
});