Core Concepts

FloImg is built around three simple operations: Generate, Transform, and Save. The power is in composing them—mix AI generation with deterministic transforms in one pipeline.

The Workflow Model

Every FloImg workflow follows this pattern:

Generate → Transform (optional, repeatable) → Save

1. Generate: Create an image—with AI (DALL-E, Stability) or deterministically (charts, QR codes)
2. Transform: Modify the image precisely (resize, adjust colors, add caption)
3. Save: Output to filesystem, S3, or other storage

Three Workflow Types

Type	Example
AI + Professional	Generate with DALL-E → resize to 1200x630 → add caption → S3
Purely Creative	AI generate → AI refine → create variations
Purely Practical	Chart → resize → format convert → CDN

Use whichever fits your task—or combine them.

Generators

Generators create images. Each generator is a plugin—install only what you need.

const image = await floimg.generate({
  generator: 'openai',  // Which generator to use
  params: { prompt: 'Product photo of wireless headphones' }
});

AI Image Generators

• openai - DALL-E 3 for high-quality AI images
• stability - Stable Diffusion (SDXL, SD3)
• google - Google Imagen
• replicate - Thousands of AI models
• ollama - Local AI models (no API key required)
• xai - Grok for text and vision

Deterministic Generators

• quickchart - Charts via Chart.js
• mermaid - Diagrams and flowcharts
• qr - QR codes
• d3 - D3 data visualizations
• screenshot - Website screenshots

See Plugins for the full list and documentation.

Transforms

Transforms modify existing images. They can be chained:

let image = await floimg.generate({ ... });

// Chain multiple transforms
image = await floimg.transform(image, { op: 'resize', params: { width: 800 } });
image = await floimg.transform(image, { op: 'blur', params: { sigma: 2 } });
image = await floimg.transform(image, { op: 'convert', params: { format: 'webp' } });

Available transforms:

• resize - Change dimensions
• blur - Apply gaussian blur
• sharpen - Sharpen edges
• convert - Change format (PNG, JPEG, WebP, etc.)
• rotate - Rotate by degrees
• crop - Crop to region

The Image Object

When you generate or transform, you get an image object (a Blob) that can be:

• Passed to another transform
• Saved to storage
• Converted to a Buffer or base64

const image = await floimg.generate({ ... });

// Get as Buffer
const buffer = await image.arrayBuffer();

// Get as base64
const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));

Storage Adapters

FloImg can save to different storage backends:

// Local filesystem
await floimg.save(image, './output.png');

// S3 bucket
await floimg.save(image, 's3://bucket/path/image.png');

// Custom adapter
floimg.registerStorage(myCustomAdapter());
await floimg.save(image, 'custom://path/image.png');

Deterministic Execution

FloImg transforms are deterministic:

Same inputs → Same outputs

When you resize, adjust colors, or convert formats, you get identical results every time. This makes FloImg ideal for CI/CD pipelines, automated reporting, and AI agent workflows.

When using AI generators (DALL-E, Stability), the generation step is non-deterministic—but the transforms after generation are still precise. This is the power of composition: creative AI generation followed by exact, repeatable transforms.

Putting It Together

Here’s a complete example mixing AI generation with deterministic transforms:

import createClient from '@teamflojo/floimg';
import openai from '@teamflojo/floimg-openai';

const floimg = createClient();
floimg.registerGenerator(openai());

// 1. Generate with AI
const image = await floimg.generate({
  generator: 'openai',
  params: { prompt: 'Professional product photo of wireless headphones' }
});

// 2. Apply deterministic transforms
const resized = await floimg.transform(image, {
  op: 'resize',
  params: { width: 1200, height: 630 }
});

const captioned = await floimg.transform(resized, {
  op: 'caption',
  params: { text: 'New Release', position: 'bottom' }
});

// 3. Save to cloud storage
await floimg.save(captioned, 's3://my-bucket/hero.png');

One pipeline: AI creativity → precise transforms → cloud delivery.

Next Steps

• SDK Reference - Detailed API documentation
• Plugins - Explore available generators
• MCP Integration - Use with AI agents