🎨 GenMix

AI-powered image generator using Google Gemini API. Supports image generation from text prompts and image modification with reference images.

Features ✨

• 🖼️ Image generation from text descriptions
• 🎨 Image modification using reference images
• 🔄 Style transfer - Apply artistic styles to your images
• 📐 Quality control - Generate in 1K, 2K or 4K
• 🎯 Multiple formats - Supports local paths, URLs and Base64
• 💾 Auto-save with unique hash per prompt

Installation

npm install genmix

Setup

Create a .env file in your project root:

GEMINI_API_KEY=your_api_key_here

Basic Usage

Simple Image Generation

const { GeminiGenerator } = require('genmix');

const generator = new GeminiGenerator();

// Generate an image
const result = await generator.generate(
  'A futuristic city with flying cars, cyberpunk style',
  {
    numberOfImages: 1,
    quality: '2K',
    aspectRatio: '16:9'
  }
);

// Save images
const savedPaths = await generator.save({ directory: './output' });
console.log('Images saved:', savedPaths);

Image Modification with Reference Images

// Modify an existing image
const result = await generator.generate(
  'Transform this image to have sunset lighting with warm orange tones',
  {
    referenceImage: './my-image.png',  // Local path
    quality: '2K',
    numberOfImages: 1
  }
);

const savedPaths = await generator.save({ directory: './output' });

Using URLs as Reference

const result = await generator.generate(
  'Convert this photo into a watercolor painting',
  {
    referenceImage: 'https://example.com/image.jpg',  // URL
    quality: '1K'
  }
);

generator.save({ directory: './output' });

Configuration Options

Constructor

new GeminiGenerator({
  apiKey: string,           // Your Google API key (required)
  modelId: string           // Model to use (optional, default: 'gemini-3-pro-image-preview')
})

generate() Method

await generator.generate(prompt, options)

Parameters:

| Option | Type | Description | Default | | ------------------------ | ------------- | ------------------------------------------- | ------- | | prompt | string | Description of what you want to generate | - | | options.referenceImage | string/Buffer | Reference image (path, URL, Base64, Buffer) | - | | options.numberOfImages | number | Number of images to generate | 1 | | options.quality | string | Quality: '1K', '2K', '4K' | - | | options.aspectRatio | string | Aspect ratio: '1:1', '16:9', '4:3', etc. | - |

save() Method

await generator.save(options)

Parameters:

| Option | Type | Description | Default | | ------------------- | ------ | ------------------------------------------------ | ------- | | options.directory | string | Target directory path to save images | '.' | | options.filename | string | Custom filename (without extension). If not provided, uses hash-based filename | - | | options.extension | string | File format: 'jpg', 'png', 'webp', 'avif', 'tiff' | 'jpg' |

Examples:

// Save to specific directory with auto-generated filename (jpg by default)
await generator.save({ directory: './output' });

// Save as PNG
await generator.save({ directory: './output', extension: 'png' });

// Save to specific directory with custom filename
await generator.save({ directory: './output', filename: 'my-image' });

// Save as WebP with custom filename
await generator.save({ directory: './output', filename: 'my-image', extension: 'webp' });

// Save to current directory with custom filename
await generator.save({ filename: 'my-image' });

// Save to current directory with auto-generated filename (jpg)
await generator.save();

Note:

• When multiple images are generated and a custom filename is provided, they will be saved as filename_0.jpg, filename_1.jpg, etc.
• The method uses Sharp for image conversion, supporting high-quality format conversion

Advanced Examples

Style Transfer

const result = await generator.generate(
  'Transform this photo into a Van Gogh style painting with visible brush strokes',
  {
    referenceImage: './photo.jpg',
    quality: '4K'
  }
);

Lighting Modification

const result = await generator.generate(
  'Change the lighting to dramatic studio lighting with strong shadows',
  {
    referenceImage: './portrait.png',
    quality: '2K'
  }
);

Multiple Variations

const result = await generator.generate(
  'Add dramatic clouds and enhance colors',
  {
    referenceImage: './landscape.jpg',
    numberOfImages: 3,
    quality: '1K'
  }
);

// Generates 3 variations of the same modification

Using Buffers

const fs = require('fs');
const imageBuffer = fs.readFileSync('./image.png');

const result = await generator.generate(
  'Make this image look cinematic',
  {
    referenceImage: imageBuffer
  }
);

Reference Image Formats

GenMix accepts reference images in multiple formats:

1. Local file path: './image.png'
2. URL: 'https://example.com/image.jpg'
3. Data URI: 'data:image/png;base64,iVBORw0KG...'
4. Buffer: Buffer.from(...)

Supported image formats: PNG, JPEG, GIF, WEBP

Error Handling

try {
  const result = await generator.generate(prompt, options);
  
  if (result.images && result.images.length > 0) {
    const paths = generator.save({ directory: './output' });
    console.log('Success!', paths);
  } else {
    console.log('No images generated');
  }
} catch (error) {
  console.error('Error:', error.message);
  
  // Common errors:
  // - 'API Key is required'
  // - 'Failed to read reference image file'
  // - 'Failed to download reference image from URL'
  // - 'Gemini API Error: ...'
}

Project Structure

genmix/
└── generators/
│   ├── BaseGenerator.js      # Base class with utilities
│   └── GeminiGenerator.js    # Gemini API implementation
├── demo/
│   ├── example.js                # Basic examples
│   └── example-translation.js    # Translate image
├── index.js                      # Entry point
└── README.md

Best Practices

1. Clear Prompts: Be specific about what you want

   // ✅ Good
   'Add dramatic sunset lighting with orange and pink tones in the sky'
      
   // ❌ Vague
   'Make it better'

2. Appropriate Quality:

   • 1K: Quick tests
   • 2K: General use
   • 4K: High quality (slower)

3. Image Size: Reference images between 512x512 and 2048x2048 work best

4. Result Caching: Images are automatically saved with unique hash based on the prompt

Additional Resources

• Code Examples
• Google Gemini API Documentation

License

MIT

Contributing

Contributions are welcome! Please open an issue or pull request.