@djangocfg/imgai

AI-powered image generation and optimization CLI for Next.js projects using OpenAI DALL-E and Claude Vision

Part of DjangoCFG — a modern Django framework for building production-ready SaaS applications. All @djangocfg/* packages are designed to work together, providing type-safe configuration, real-time features, and beautiful admin interfaces out of the box.

AI-powered image generation & management for Next.js projects.

Features

• 🎨 AI Image Generation - Generate images using OpenAI DALL-E 3 or Claude
• 🔍 Image Scanner - Automatically find and catalog all images in your project
• ⚡ Config Sync - Generate TypeScript config with all images for type-safe access
• 📦 Batch Processing - Generate multiple images with concurrent workers
• 🖼️ Image Optimization - Automatic resize and format conversion (WebP, AVIF)
• 🎯 Beautiful CLI - Interactive and command-line interfaces

Installation

pnpm add @djangocfg/imgai

Quick Start

Interactive Mode

npx imgai

Generate Single Image

npx imgai generate "A beautiful sunset over mountains" --filename sunset --category backgrounds

Scan & Sync

# Scan all images
npx imgai scan

# Generate images.ts config
npx imgai sync

Batch Generate

Create a prompts.json file:

[
  { "prompt": "Abstract blue waves", "filename": "waves" },
  { "prompt": "Geometric patterns", "filename": "patterns" },
  "Simple prompt without filename"
]

Then run:

npx imgai batch prompts.json --category abstract --concurrency 2

Programmatic Usage

import { createImageAI, generateImage, scanImages, syncImagesConfig } from '@djangocfg/imgai';

// Quick helpers
const result = await generateImage('A beautiful landscape', {
  projectRoot: process.cwd(),
});

const images = await scanImages({
  projectRoot: process.cwd(),
});

await syncImagesConfig({
  projectRoot: process.cwd(),
});

// Full control
const { generator, scanner, configGenerator } = createImageAI({
  projectRoot: process.cwd(),
  provider: 'openai',
  size: '1792x1024',
  quality: 'hd',
  resize: {
    width: 800,
    height: 600,
    format: 'webp',
    quality: 85,
  },
});

// Generate with enhanced prompt
const enhanced = await generator.enhancePrompt('A tech company landing page hero');
const image = await generator.generate({
  prompt: enhanced.prompt,
  filename: enhanced.filename,
  category: 'heroes',
});

// Batch generate
const batchResult = await generator.generateBatch({
  items: [
    { prompt: 'Image 1', category: 'batch' },
    { prompt: 'Image 2', category: 'batch' },
  ],
  concurrency: 2,
  onProgress: (current, total, result) => {
    console.log(`${current}/${total}: ${result.success ? '✓' : '✗'}`);
  },
});

// Scan images
const catalog = await scanner.buildCatalog();
console.log(`Found ${catalog.count} images`);

// Generate images.ts
await configGenerator.generate();

Generated Config (images.ts)

After running imgai sync, you get a fully typed images.ts:

import { getImage, getImageUrl, getImagesByCategory, hasImage } from '@/core/images';

// Type-safe image access
const heroImage = getImage('hero-landing');
const heroUrl = getImageUrl('hero-landing');

// Get all images in category
const backgroundImages = getImagesByCategory('backgrounds');

// Check if image exists
if (hasImage('my-image')) {
  // TypeScript knows it exists
}

CLI Commands

imgai [interactive]    Start interactive mode (default)
imgai generate <prompt> Generate single image
imgai scan             Scan and list all images
imgai sync             Generate/update images.ts
imgai batch <file>     Batch generate from JSON file

Options

Generate Options

-f, --filename <name>  Output filename
-c, --category <name>  Category/folder (default: general)
-r, --root <path>      Project root directory
-o, --output <path>    Output directory
--size <size>          Image size (1024x1024, 1792x1024, 1024x1792)
--quality <quality>    Image quality (standard, hd)
--style <style>        Style prefix for prompts
--resize               Enable resize
--width <pixels>       Resize width
--height <pixels>      Resize height
--format <format>      Output format (webp, jpeg, png, avif)

Scan Options

-r, --root <path>      Project root directory
-d, --dirs <dirs>      Directories to scan (comma-separated)
--no-dimensions        Skip reading image dimensions

Environment Variables

OPENAI_API_KEY=sk-...      # Required for image generation
ANTHROPIC_API_KEY=sk-ant-... # Optional for prompt enhancement with Claude

Documentation

Full documentation available at djangocfg.com

Contributing

Issues and pull requests are welcome at GitHub

License

MIT - see LICENSE for details