genmix 1.0.2 → 1.0.5

package/README.md

@@ -17,6 +17,13 @@ AI-powered image generator using Google Gemini API. Supports image generation fr
 npm install genmix
 ```
 
+### AI Skill
+You can also add GenMix as a skill for AI agentic development:
+
+```bash
+npx skills add https://github.com/clasen/GenMix --skill genmix
+```
+
 ## Setup
 
 Create a `.env` file in your project root:
@@ -27,10 +34,47 @@ GEMINI_API_KEY=your_api_key_here
 
 ## Basic Usage
 
+### The Power of GenMix: Multiple References & Chainable API
+
+GenMix shines when combining multiple images with specific instructions using its intuitive chainable API:
+
+```javascript
+import { GeminiGenerator } from 'genmix';
+const generator = new GeminiGenerator();
+
+const result = await generator
+  .pro() // Use the Pro model for best results
+  .addReference('./person.jpg', 'Use this person as the main subject')
+  .addReference('./background.jpg', 'Use this as the background setting')
+  .generate('A photo of the person standing in the background setting, cinematic lighting');
+
+await generator.save({ filename: 'composite-result' });
+```
+
+### Model Selection
+
+You can easily switch between the Pro and Flash models using chainable methods:
+
+```javascript
+import { GeminiGenerator } from 'genmix';
+
+const generator = new GeminiGenerator();
+
+// Use the Pro model
+await generator
+  .pro()
+  .generate('A highly detailed portrait of a cat');
+
+// Switch to the Flash model
+await generator
+  .flash()
+  .generate('A quick sketch of a dog');
+```
+
 ### Simple Image Generation
 
 ```javascript
-const { GeminiGenerator } = require('genmix');
+import { GeminiGenerator } from 'genmix';
 
 const generator = new GeminiGenerator();
 
@@ -90,6 +134,23 @@ new GeminiGenerator({
 })
 ```
 
+### Model Selection Methods
+
+```javascript
+generator.pro()    // Switches to the gemini-3-pro-image-preview model
+generator.flash()  // Switches to the gemini-3.1-flash-image-preview model
+```
+Both methods are chainable and return the generator instance.
+
+### Reference Methods
+
+You can also use chainable methods to add one or multiple reference images before calling `generate()`:
+
+```javascript
+generator.addReference(image, description) // Adds a reference image (path, URL, Buffer)
+generator.clearReferences()                // Removes all queued reference images
+```
+
 ### generate() Method
 
 ```javascript
@@ -190,7 +251,7 @@ const result = await generator.generate(
 ### Using Buffers
 
 ```javascript
-const fs = require('fs');
+import fs from 'fs';
 const imageBuffer = fs.readFileSync('./image.png');
 
 const result = await generator.generate(

package/demo/example-multiple.js

@@ -0,0 +1,47 @@
+process.loadEnvFile();
+import { GeminiGenerator } from '../index.js';
+import path from 'path';
+import fs from 'fs';
+
+async function main() {
+    try {
+        const generator = new GeminiGenerator();
+
+        const localImagePath = path.join(import.meta.dirname, 'camera_4126.jpg');
+
+        if (fs.existsSync(localImagePath)) {
+            console.log('🎨 Generating multiple variations...\n');
+
+            const result = await generator.generate(
+                'Add a vintage film look with grain and vignette effect',
+                {
+                    referenceImage: localImagePath,
+                    quality: '1K',
+                    numberOfImages: 3
+                }
+            );
+
+            if (result.images && result.images.length > 0) {
+                const saved = await generator.save({ directory: import.meta.dirname });
+                console.log(`✅ ${saved.length} variations saved:`);
+                saved.forEach(p => console.log(`   - ${p}`));
+                console.log();
+            }
+        }
+
+        console.log('🎉 Example completed successfully!\n');
+
+    } catch (error) {
+        console.error('❌ Error:', error.message);
+
+        if (error.message.includes('API Key')) {
+            console.error('\n💡 Tip: Make sure you have GEMINI_API_KEY in your .env file');
+        }
+
+        if (error.message.includes('reference image')) {
+            console.error('\n💡 Tip: Verify that the image path is correct');
+        }
+    }
+}
+
+main();

package/demo/example-references.js

@@ -0,0 +1,51 @@
+try { process.loadEnvFile(); } catch (error) { }
+import { GeminiGenerator } from '../index.js';
+import path from 'path';
+
+
+try {
+    const generator = new GeminiGenerator();
+
+    const background = path.join(import.meta.dirname, 'background.jpg');
+    const subject = path.join(import.meta.dirname, 'selfie.jpg');
+
+    console.log('🖼️  Adding references...');
+    generator
+        .addReference(background, 'use as background landscape')
+        .addReference(subject, 'use as the main subject');
+
+    console.log('🎨 Generating composite image...\n');
+
+    const result = await generator.generate(
+        'Place the subject in front of the background, cinematic lighting, golden hour',
+        { quality: '2K' }
+    );
+
+    if (result.text) {
+        console.log('📝 Model notes:', result.text);
+    }
+
+    if (result.images && result.images.length > 0) {
+        const saved = await generator.save({
+            directory: import.meta.dirname,
+            filename: 'composite-result'
+        });
+        console.log(`✅ Saved: ${saved[0]}\n`);
+    } else {
+        console.log('⚠️  No images generated.\n');
+    }
+
+    console.log('🎉 Example completed!\n');
+
+} catch (error) {
+    console.error('❌ Error:', error.message);
+
+    if (error.message.includes('API Key')) {
+        console.error('\n💡 Tip: Make sure you have GEMINI_API_KEY in your .env file');
+    }
+
+    if (error.message.includes('reference image')) {
+        console.error('\n💡 Tip: Place background.jpg and subject.jpg in the demo/ folder');
+    }
+}
+

package/demo/example-translate.js

@@ -1,14 +1,13 @@
-process.loadEnvFile(); // Native Node.js .env loading (Node 20.12+)
-const { GeminiGenerator } = require('../index');
-const path = require('path');
-const fs = require('fs');
+process.loadEnvFile();
+import { GeminiGenerator } from '../index.js';
+import path from 'path';
+import fs from 'fs';
 
 async function main() {
     try {
         const generator = new GeminiGenerator();
 
-        // === Option 1: Use a local image ===
-        const localImagePath = path.join(__dirname, 'camera_4126.jpg');
+        const localImagePath = path.join(import.meta.dirname, 'camera_4126.jpg');
 
         if (fs.existsSync(localImagePath)) {
             console.log('📸 Processing local image...\n');
@@ -23,18 +22,20 @@ async function main() {
             );
 
             if (result1.images && result1.images.length > 0) {
-                // Create pt directory if it doesn't exist
-                const ptDir = path.join(__dirname, 'pt');
+                const ptDir = path.join(import.meta.dirname, 'pt');
                 if (!fs.existsSync(ptDir)) {
                     fs.mkdirSync(ptDir, { recursive: true });
                 }
-                
-                // Use the same filename as the original
+
                 const originalName = path.basename(localImagePath, path.extname(localImagePath));
-                
-                const saved = await generator.save({ 
+
+                const refMetadata = generator.getReferenceMetadata();
+                console.log('📊 Reference format:', refMetadata);
+
+                const saved = await generator.save({
                     directory: ptDir,
-                    filename: originalName
+                    filename: originalName,
+                    formatOptions: refMetadata
                 });
                 console.log('✅ Modified image saved at:', saved[0], '\n');
             } else if (result1.text) {
@@ -42,29 +43,7 @@ async function main() {
             }
         }
 
-
-        // // === Option 3: Multiple variations of the same image ===
-        // if (fs.existsSync(localImagePath)) {
-        //     console.log('🎨 Generating multiple variations...\n');
-
-        //     const result3 = await generator.generate(
-        //         'Add a vintage film look with grain and vignette effect',
-        //         {
-        //             referenceImage: localImagePath,
-        //             quality: '1K',
-        //             numberOfImages: 3
-        //         }
-        //     );
-
-        //     if (result3.images && result3.images.length > 0) {
-        //         const saved = await generator.save({ directory: __dirname });
-        //         console.log(`✅ ${saved.length} variations saved:`);
-        //         saved.forEach(p => console.log(`   - ${p}`));
-        //         console.log();
-        //     }
-        // }
-
-        console.log('🎉 All examples completed successfully!\n');
+        console.log('🎉 Example completed successfully!\n');
 
     } catch (error) {
         console.error('❌ Error:', error.message);
@@ -80,4 +59,3 @@ async function main() {
 }
 
 main();
-

package/demo/example.js

@@ -1,6 +1,5 @@
-process.loadEnvFile(); // Native Node.js .env loading (Node 20.12+)
-const { GeminiGenerator } = require('../index');
-
+process.loadEnvFile();
+import { GeminiGenerator } from '../index.js';
 
 async function exampleBasicGeneration() {
     console.log('\n=== Example 1: Basic Image Generation ===\n');
@@ -12,7 +11,7 @@ async function exampleBasicGeneration() {
     console.log('Generating image...');
     const result = await generator.generate(prompt, {
         numberOfImages: 2,
-        quality: '1K', // Options: 1K, 2K, 4K
+        quality: '1K',
         aspectRatio: '1:1'
     });
 
@@ -25,20 +24,16 @@ async function exampleBasicGeneration() {
     if (result.images && result.images.length > 0) {
         console.log(`Found ${result.images.length} images.`);
 
-        const savedPaths = await generator.save({ directory: __dirname });
+        const savedPaths = await generator.save({ directory: import.meta.dirname });
         savedPaths.forEach(p => console.log(`Saved image to ${p}`));
     } else {
         console.log('No images generated.');
     }
 }
 
-
-
 async function main() {
     try {
-        // Example 1: Basic generation
         await exampleBasicGeneration();
-
         console.log('\n=== All examples completed! ===\n');
     } catch (error) {
         console.error('Error:', error.message);

package/demo/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "demo",
+  "version": "1.0.0",
+  "description": "",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/generators/BaseGenerator.js

@@ -26,9 +26,10 @@ class BaseGenerator {
      * @param {string} [options.directory='.'] - Target directory path. Defaults to current directory.
      * @param {string} [options.filename] - Optional custom filename (without extension). If not provided, uses hashed filenames.
      * @param {string} [options.extension='jpg'] - File extension: 'jpg', 'png', 'webp', 'avif', 'tiff'. Defaults to 'jpg'.
+     * @param {Object} [options.formatOptions] - Format-specific options (quality, compressionLevel, palette, colours, etc.)
      * @returns {Promise<string[]>} Promise that resolves to array of saved file paths.
      */
-    async save({directory = '.', filename = null, extension = 'jpg'} = {}) {
+    async save({directory = '.', filename = null, extension = 'jpg', formatOptions = null} = {}) {
         const targetImages = this.lastGeneration?.images;
         const targetPrompt = this.lastGeneration?.prompt;
 
@@ -46,6 +47,11 @@ class BaseGenerator {
             fs.mkdirSync(directory, { recursive: true });
         }
 
+        // Use format from formatOptions if provided, otherwise use extension
+        if (formatOptions && formatOptions.format) {
+            extension = formatOptions.format;
+        }
+
         // Normalize extension
         extension = extension.toLowerCase().replace(/^\./, '');
         
@@ -84,8 +90,46 @@ class BaseGenerator {
 
             // Convert image format using sharp
             try {
-                await sharp(buffer)
-                    .toFormat(sharpFormat)
+                let sharpInstance = sharp(buffer);
+                
+                // Resize if dimensions are specified in formatOptions
+                if (formatOptions && formatOptions.width && formatOptions.height) {
+                    sharpInstance = sharpInstance.resize(formatOptions.width, formatOptions.height, {
+                        fit: 'fill'
+                    });
+                }
+                
+                // Build format-specific options
+                const sharpFormatOptions = {};
+                
+                if (formatOptions) {
+                    if (sharpFormat === 'jpg' && formatOptions.quality) {
+                        sharpFormatOptions.quality = formatOptions.quality;
+                    } else if (sharpFormat === 'png') {
+                        if (formatOptions.compressionLevel !== undefined) {
+                            sharpFormatOptions.compressionLevel = formatOptions.compressionLevel;
+                        }
+                        if (formatOptions.quality !== undefined) {
+                            sharpFormatOptions.quality = formatOptions.quality;
+                        }
+                        if (formatOptions.effort !== undefined) {
+                            sharpFormatOptions.effort = formatOptions.effort;
+                        }
+                        if (formatOptions.palette) {
+                            sharpFormatOptions.palette = true;
+                            // Add dithering for better quality with palette
+                            sharpFormatOptions.dither = 1.0;
+                        }
+                        if (formatOptions.colours) {
+                            sharpFormatOptions.colours = formatOptions.colours;
+                        }
+                    } else if (sharpFormat === 'webp' && formatOptions.quality) {
+                        sharpFormatOptions.quality = formatOptions.quality;
+                    }
+                }
+                
+                await sharpInstance
+                    .toFormat(sharpFormat, sharpFormatOptions)
                     .toFile(outputPath);
                 
                 savedPaths.push(outputPath);

package/generators/GeminiGenerator.js

@@ -4,261 +4,400 @@ const fs = require('fs');
 const path = require('path');
 
 class GeminiGenerator extends BaseGenerator {
-  /**
-   * @param {Object} [config]
-   * @param {string} [config.apiKey]
-   * @param {string} [config.modelId]
-   */
-  constructor(config = {}) {
-    super(config);
-    this.apiKey = config.apiKey || process.env.GEMINI_API_KEY;
-
-    if (!this.apiKey) {
-      throw new Error('API Key is required. Provide it in the constructor or set GEMINI_API_KEY environment variable.');
+    static MODELS = {
+        PRO: 'gemini-3-pro-image-preview',
+        FLASH: 'gemini-3.1-flash-image-preview',
+    };
+
+    /**
+     * @param {Object} [config]
+     * @param {string} [config.apiKey]
+     * @param {string} [config.modelId] - Model ID or use GeminiGenerator.MODELS constants
+     */
+    constructor(config = {}) {
+        super(config);
+        this.apiKey = config.apiKey || process.env.GEMINI_API_KEY;
+
+        if (!this.apiKey) {
+            throw new Error('API Key is required. Provide it in the constructor or set GEMINI_API_KEY environment variable.');
+        }
+        this.modelId = config.modelId || GeminiGenerator.MODELS.FLASH;
+        this.apiUrl = `https://generativelanguage.googleapis.com/v1beta/models/${this.modelId}:streamGenerateContent`;
+        this.referenceMetadata = null;
+        this.references = [];
     }
-    // Use the specific model for image generation or default to pro-vision if needed
-    // However, for standard image generation via prompt, specific models like 'gemini-1.5-pro' or 'imagen-3.0-generate-001' are often used.
-    // Keeping the user's modelId preference.
-    this.modelId = config.modelId || 'gemini-3-pro-image-preview';
-    // NOTE: For simple generation, we might not need streamGenerateContent unless we want text streaming.
-    // But let's stick to what worked for text, and adjust the body.
-    this.apiUrl = `https://generativelanguage.googleapis.com/v1beta/models/${this.modelId}:streamGenerateContent`;
-  }
-
-  /**
-   * @param {string} prompt
-   * @param {Object} [options]
-   * @param {string|Buffer} [options.referenceImage] - Path to image file, base64 data URI, or Buffer
-   * @param {string} [options.numberOfImages] - Number of images to generate
-   * @param {string} [options.quality] - Image quality: '1K', '2K', '4K'
-   * @param {string} [options.aspectRatio] - Aspect ratio like '1:1', '16:9', etc.
-   * @returns {Promise<{images: string[], text: string, raw: any}>}
-   */
-  async generate(prompt, options = {}) {
-    // If the user asks for multiple images, we might need to make parallel requests
-    // if the API doesn't support candidateCount > 1 for images.
-    // Based on search results, candidateCount > 1 can cause 400 errors.
-    const numberOfImages = options.numberOfImages || 1;
-
-    let result;
-    if (numberOfImages > 1) {
-      result = await this.generateMultiple(prompt, numberOfImages, options);
-    } else {
-      result = await this._generateSingleRequest(prompt, options);
+
+    /**
+     * Add a reference image to be included in the next generate() call.
+     * @param {string|Buffer} image - Path to image file, URL, base64 data URI, or Buffer
+     * @param {string} [description] - How the model should use this image (e.g. 'use as background')
+     * @returns {GeminiGenerator} this instance for chaining
+     */
+    addReference(image, description = '') {
+        this.references.push({ image, description });
+        return this;
     }
 
-    // Store result in state for saveImages()
-    this.lastGeneration = {
-        prompt: prompt,
-        images: result.images,
-        text: result.text,
-        raw: result.raw
-    };
+    /**
+     * Remove all queued reference images.
+     * @returns {GeminiGenerator} this instance for chaining
+     */
+    clearReferences() {
+        this.references = [];
+        return this;
+    }
+
+    /**
+     * Switch to the Pro model
+     * @returns {GeminiGenerator} this instance for chaining
+     */
+    pro() {
+        this.modelId = GeminiGenerator.MODELS.PRO;
+        this.apiUrl = `https://generativelanguage.googleapis.com/v1beta/models/${this.modelId}:streamGenerateContent`;
+        return this;
+    }
+
+    /**
+     * Switch to the Flash model
+     * @returns {GeminiGenerator} this instance for chaining
+     */
+    flash() {
+        this.modelId = GeminiGenerator.MODELS.FLASH;
+        this.apiUrl = `https://generativelanguage.googleapis.com/v1beta/models/${this.modelId}:streamGenerateContent`;
+        return this;
+    }
+
+    /**
+     * @param {string} prompt
+     * @param {Object} [options]
+     * @param {string|Buffer} [options.referenceImage] - Path to image file, base64 data URI, or Buffer (legacy single-image API)
+     * @param {string} [options.numberOfImages] - Number of images to generate
+     * @param {string} [options.quality] - Image quality: '1K', '2K', '4K'
+     * @param {string} [options.aspectRatio] - Aspect ratio like '1:1', '16:9', etc.
+     * @returns {Promise<{images: string[], text: string, raw: any}>}
+     */
+    async generate(prompt, options = {}) {
+        // If the user asks for multiple images, we might need to make parallel requests
+        // if the API doesn't support candidateCount > 1 for images.
+        // Based on search results, candidateCount > 1 can cause 400 errors.
+        const numberOfImages = options.numberOfImages || 1;
+
+        let result;
+        if (numberOfImages > 1) {
+            result = await this.generateMultiple(prompt, numberOfImages, options);
+        } else {
+            result = await this._generateSingleRequest(prompt, options);
+        }
+
+        // Store result in state for saveImages()
+        this.lastGeneration = {
+            prompt: prompt,
+            images: result.images,
+            text: result.text,
+            raw: result.raw
+        };
+
+        this.references = [];
+
+        return result;
+    }
+
+    /**
+     * Processes a reference image and returns base64 data and mime type
+     * @param {string|Buffer} imageInput - File path, base64 data URI, or Buffer
+     * @returns {Promise<{data: string, mimeType: string}>}
+     * @private
+     */
+    async _processReferenceImage(imageInput) {
+        let base64Data;
+        let mimeType = 'image/png'; // default
+
+        if (Buffer.isBuffer(imageInput)) {
+            // If it's already a buffer
+            base64Data = imageInput.toString('base64');
+        } else if (typeof imageInput === 'string') {
+            if (imageInput.startsWith('data:image/')) {
+                // It's a data URI
+                const match = imageInput.match(/^data:(image\/[^;]+);base64,(.+)$/);
+                if (match) {
+                    mimeType = match[1];
+                    base64Data = match[2];
+                } else {
+                    throw new Error('Invalid data URI format for reference image');
+                }
+            } else if (imageInput.startsWith('http://') || imageInput.startsWith('https://')) {
+                // It's a URL - download it
+                try {
+                    const response = await axios.get(imageInput, { responseType: 'arraybuffer' });
+                    base64Data = Buffer.from(response.data).toString('base64');
+                    mimeType = response.headers['content-type'] || 'image/png';
+                } catch (error) {
+                    throw new Error(`Failed to download reference image from URL: ${error.message}`);
+                }
+            } else {
+                // Assume it's a file path
+                try {
+                    const fileBuffer = fs.readFileSync(imageInput);
+                    base64Data = fileBuffer.toString('base64');
 
-    return result;
-  }
-
-  /**
-   * Processes a reference image and returns base64 data and mime type
-   * @param {string|Buffer} imageInput - File path, base64 data URI, or Buffer
-   * @returns {Promise<{data: string, mimeType: string}>}
-   * @private
-   */
-  async _processReferenceImage(imageInput) {
-    let base64Data;
-    let mimeType = 'image/png'; // default
-
-    if (Buffer.isBuffer(imageInput)) {
-      // If it's already a buffer
-      base64Data = imageInput.toString('base64');
-    } else if (typeof imageInput === 'string') {
-      if (imageInput.startsWith('data:image/')) {
-        // It's a data URI
-        const match = imageInput.match(/^data:(image\/[^;]+);base64,(.+)$/);
-        if (match) {
-          mimeType = match[1];
-          base64Data = match[2];
+                    // Determine mime type from extension
+                    const ext = path.extname(imageInput).toLowerCase();
+                    const mimeTypes = {
+                        '.png': 'image/png',
+                        '.jpg': 'image/jpeg',
+                        '.jpeg': 'image/jpeg',
+                        '.gif': 'image/gif',
+                        '.webp': 'image/webp'
+                    };
+                    mimeType = mimeTypes[ext] || 'image/png';
+
+                    // Extract metadata from reference image using sharp
+                    await this._extractReferenceMetadata(imageInput);
+                } catch (error) {
+                    throw new Error(`Failed to read reference image file: ${error.message}`);
+                }
+            }
         } else {
-          throw new Error('Invalid data URI format for reference image');
+            throw new Error('Reference image must be a file path, URL, data URI, or Buffer');
         }
-      } else if (imageInput.startsWith('http://') || imageInput.startsWith('https://')) {
-        // It's a URL - download it
+
+        return { data: base64Data, mimeType };
+    }
+
+    /**
+     * Extract metadata from reference image
+     * @param {string} imagePath - Path to the reference image
+     * @private
+     */
+    async _extractReferenceMetadata(imagePath) {
+        const sharp = require('sharp');
         try {
-          const response = await axios.get(imageInput, { responseType: 'arraybuffer' });
-          base64Data = Buffer.from(response.data).toString('base64');
-          mimeType = response.headers['content-type'] || 'image/png';
+            const image = sharp(imagePath);
+            const metadata = await image.metadata();
+            const stats = fs.statSync(imagePath);
+
+            // Build format options based on image format
+            const formatOptions = {
+                format: metadata.format,
+                width: metadata.width,
+                height: metadata.height
+            };
+
+            // Format-specific options
+            if (metadata.format === 'jpeg' || metadata.format === 'jpg') {
+                // Estimate quality from file size (heuristic)
+                const pixelCount = metadata.width * metadata.height;
+                const bytesPerPixel = stats.size / pixelCount;
+
+                // Quality estimation based on bytes per pixel
+                if (bytesPerPixel < 0.5) formatOptions.quality = 70;
+                else if (bytesPerPixel < 1) formatOptions.quality = 80;
+                else if (bytesPerPixel < 1.5) formatOptions.quality = 90;
+                else formatOptions.quality = 90;
+            } else if (metadata.format === 'png') {
+                formatOptions.compressionLevel = 9;
+
+                // Check if it's a palette PNG using paletteBitDepth
+                if (metadata.paletteBitDepth) {
+                    formatOptions.palette = true;
+                    formatOptions.quality = 90; // Max quality for palette PNG
+                    formatOptions.effort = 9; // Maximum compression effort
+
+                    // Count actual unique colors in the image
+                    try {
+                        const { data, info } = await sharp(imagePath).raw().toBuffer({ resolveWithObject: true });
+                        const colors = new Set();
+                        const pixelSize = info.channels;
+
+                        for (let i = 0; i < data.length; i += pixelSize) {
+                            const color = [];
+                            for (let j = 0; j < pixelSize; j++) {
+                                color.push(data[i + j]);
+                            }
+                            colors.add(color.join(','));
+                        }
+
+                        formatOptions.colours = colors.size;
+                    } catch (error) {
+                        // Fallback to paletteBitDepth calculation if color counting fails
+                        formatOptions.colours = Math.pow(2, metadata.paletteBitDepth);
+                    }
+                }
+            } else if (metadata.format === 'webp') {
+                formatOptions.quality = 80;
+            }
+
+            this.referenceMetadata = formatOptions;
         } catch (error) {
-          throw new Error(`Failed to download reference image from URL: ${error.message}`);
+            console.warn('Could not extract reference metadata:', error.message);
         }
-      } else {
-        // Assume it's a file path
+    }
+
+    /**
+     * Get metadata from the last processed reference image
+     * @returns {Object|null} Metadata object or null if no reference processed
+     */
+    getReferenceMetadata() {
+        return this.referenceMetadata;
+    }
+
+    async generateMultiple(prompt, count, options) {
+        const promises = [];
+        for (let i = 0; i < count; i++) {
+            promises.push(this._generateSingleRequest(prompt, options));
+        }
+
         try {
-          const fileBuffer = fs.readFileSync(imageInput);
-          base64Data = fileBuffer.toString('base64');
-          
-          // Determine mime type from extension
-          const ext = path.extname(imageInput).toLowerCase();
-          const mimeTypes = {
-            '.png': 'image/png',
-            '.jpg': 'image/jpeg',
-            '.jpeg': 'image/jpeg',
-            '.gif': 'image/gif',
-            '.webp': 'image/webp'
-          };
-          mimeType = mimeTypes[ext] || 'image/png';
+            const results = await Promise.all(promises);
+
+            const merged = {
+                images: [],
+                text: '',
+                raw: results.map(r => r.raw),
+            };
+
+            for (const res of results) {
+                merged.images.push(...res.images);
+                if (res.text && !merged.text.includes(res.text)) {
+                    merged.text += res.text + '\n';
+                }
+            }
+            return merged;
         } catch (error) {
-          throw new Error(`Failed to read reference image file: ${error.message}`);
+            throw error;
         }
-      }
-    } else {
-      throw new Error('Reference image must be a file path, URL, data URI, or Buffer');
     }
 
-    return { data: base64Data, mimeType };
-  }
+    /**
+     * Builds the API parts array from queued references + prompt.
+     * Each reference becomes [inlineData, text description (if any)], followed by the main prompt.
+     * @param {string} prompt
+     * @returns {Promise<Object[]>}
+     * @private
+     */
+    async _buildReferenceParts(prompt) {
+        const parts = [];
+
+        for (const ref of this.references) {
+            const imageData = await this._processReferenceImage(ref.image);
+            parts.push({
+                inlineData: {
+                    mimeType: imageData.mimeType,
+                    data: imageData.data
+                }
+            });
+            if (ref.description) {
+                parts.push({ text: `Reference: ${ref.description}` });
+            }
+        }
 
-  async generateMultiple(prompt, count, options) {
-    const promises = [];
-    for (let i = 0; i < count; i++) {
-      promises.push(this._generateSingleRequest(prompt, options));
+        parts.push({ text: prompt });
+        return parts;
     }
 
-    try {
-      const results = await Promise.all(promises);
-      
-      const merged = {
-        images: [],
-        text: '',
-        raw: results.map(r => r.raw),
-      };
-
-      for (const res of results) {
-        merged.images.push(...res.images);
-        if (res.text && !merged.text.includes(res.text)) {
-             merged.text += res.text + '\n';
+    async _generateSingleRequest(prompt, options) {
+        const url = `${this.apiUrl}?key=${this.apiKey}`;
+
+        // Legacy single-image API: promote to references for unified code path
+        if (options.referenceImage && this.references.length === 0) {
+            this.addReference(options.referenceImage);
         }
-      }
-      return merged;
-    } catch (error) {
-      throw error;
-    }
-  }
-
-  async _generateSingleRequest(prompt, options) {
-     const url = `${this.apiUrl}?key=${this.apiKey}`;
-
-     // Build the parts array
-     const parts = [];
-     
-     // Add reference image if provided
-     if (options.referenceImage) {
-       const imageData = await this._processReferenceImage(options.referenceImage);
-       parts.push({
-         inlineData: {
-           mimeType: imageData.mimeType,
-           data: imageData.data
-         }
-       });
-     }
-     
-     // Add text prompt
-     parts.push({
-       text: prompt,
-     });
-
-     // Simplified data structure to minimize conflicts
-     const data = {
-      contents: [
-        {
-          role: 'user', // Role is good practice
-          parts: parts,
-        },
-      ],
-      // Only include generationConfig if there are specific options to set
-      generationConfig: {
-         // 'responseModalities' is often implied or specific to the model.
-         // Removing explicit 'responseModalities' might help if the model detects intent from prompt.
-         // But let's keep basic structure.
-         // candidateCount MUST be 1 for many image models per request.
-         candidateCount: 1, 
-      },
-    };
-    
-    // Only add imageConfig if it's actually supported/needed. 
-    // Some models might reject 'imageConfig' inside 'generationConfig' if they expect text.
-    // However, if we are targeting an image model, we need to be careful.
-    // Let's try sending a cleaner request first.
-    
-    // If specific image options are passed, add them carefully
-    if (options.imageSize || options.aspectRatio || options.quality) {
-         // Note: Not all models support 'imageConfig' this way. 
-         // But if the user is using a model that supports it...
-         data.generationConfig.imageConfig = {};
-         
-         // User mentioned quality is 1k, 2k, 4k. Mapping quality or imageSize to this.
-         const size = options.quality || options.imageSize;
-         if (size) {
-             data.generationConfig.imageConfig.image_size = size; // Expects '1K', '2K', '4K'
-         }
-         
-         if (options.aspectRatio) {
-             data.generationConfig.imageConfig.aspect_ratio = options.aspectRatio;
-         }
-    }
 
-    // Remove 'tools' unless explicitly requested or needed for search grounding.
-    // 'googleSearch' tool might conflict with pure image generation intent on some endpoints.
-    // data.tools = ... (removed)
-
-    try {
-      const response = await axios.post(url, data, {
-        headers: {
-          'Content-Type': 'application/json',
-        },
-      });
-
-      return this.processResponse(response.data);
-    } catch (error) {
-      const errorMessage = error.response?.data?.error?.message || error.message;
-      // Log detailed error for debugging
-      if (error.response?.data) {
-          console.error("API Error Details:", JSON.stringify(error.response.data, null, 2));
-      }
-      throw new Error(`Gemini API Error: ${errorMessage}`);
-    }
-  }
-
-  processResponse(data) {
-    // Handle stream response which might be an array of chunks
-    const chunks = Array.isArray(data) ? data : [data];
-    const images = [];
-    let fullText = '';
-
-    for (const chunk of chunks) {
-      if (chunk.candidates) {
-        for (const candidate of chunk.candidates) {
-          if (candidate.content && candidate.content.parts) {
-            for (const part of candidate.content.parts) {
-              if (part.text) {
-                fullText += part.text;
-              }
-              if (part.inlineData && part.inlineData.mimeType.startsWith('image/')) {
-                // Base64 image data
-                images.push(`data:${part.inlineData.mimeType};base64,${part.inlineData.data}`);
-              }
-              // Handle executable code or other parts if necessary
+        const parts = await this._buildReferenceParts(prompt);
+
+        // Simplified data structure to minimize conflicts
+        const data = {
+            contents: [
+                {
+                    role: 'user', // Role is good practice
+                    parts: parts,
+                },
+            ],
+            // Only include generationConfig if there are specific options to set
+            generationConfig: {
+                // 'responseModalities' is often implied or specific to the model.
+                // Removing explicit 'responseModalities' might help if the model detects intent from prompt.
+                // But let's keep basic structure.
+                // candidateCount MUST be 1 for many image models per request.
+                candidateCount: 1,
+            },
+        };
+
+        // Only add imageConfig if it's actually supported/needed. 
+        // Some models might reject 'imageConfig' inside 'generationConfig' if they expect text.
+        // However, if we are targeting an image model, we need to be careful.
+        // Let's try sending a cleaner request first.
+
+        // If specific image options are passed, add them carefully
+        if (options.imageSize || options.aspectRatio || options.quality) {
+            // Note: Not all models support 'imageConfig' this way. 
+            // But if the user is using a model that supports it...
+            data.generationConfig.imageConfig = {};
+
+            // User mentioned quality is 1k, 2k, 4k. Mapping quality or imageSize to this.
+            const size = options.quality || options.imageSize;
+            if (size) {
+                data.generationConfig.imageConfig.image_size = size; // Expects '1K', '2K', '4K'
+            }
+
+            if (options.aspectRatio) {
+                data.generationConfig.imageConfig.aspect_ratio = options.aspectRatio;
             }
-          }
         }
-      }
+
+        // Remove 'tools' unless explicitly requested or needed for search grounding.
+        // 'googleSearch' tool might conflict with pure image generation intent on some endpoints.
+        // data.tools = ... (removed)
+
+        try {
+            const response = await axios.post(url, data, {
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+
+            return this.processResponse(response.data);
+        } catch (error) {
+            const errorMessage = error.response?.data?.error?.message || error.message;
+            // Log detailed error for debugging
+            if (error.response?.data) {
+                console.error("API Error Details:", JSON.stringify(error.response.data, null, 2));
+            }
+            throw new Error(`Gemini API Error: ${errorMessage}`);
+        }
     }
 
-    return {
-      images,
-      text: fullText,
-      raw: data,
-    };
-  }
+    processResponse(data) {
+        // Handle stream response which might be an array of chunks
+        const chunks = Array.isArray(data) ? data : [data];
+        const images = [];
+        let fullText = '';
+
+        for (const chunk of chunks) {
+            if (chunk.candidates) {
+                for (const candidate of chunk.candidates) {
+                    if (candidate.content && candidate.content.parts) {
+                        for (const part of candidate.content.parts) {
+                            if (part.text) {
+                                fullText += part.text;
+                            }
+                            if (part.inlineData && part.inlineData.mimeType.startsWith('image/')) {
+                                // Base64 image data
+                                images.push(`data:${part.inlineData.mimeType};base64,${part.inlineData.data}`);
+                            }
+                            // Handle executable code or other parts if necessary
+                        }
+                    }
+                }
+            }
+        }
+
+        return {
+            images,
+            text: fullText,
+            raw: data,
+        };
+    }
 }
 
 module.exports = GeminiGenerator;

package/index.js

@@ -2,5 +2,6 @@ const GeminiGenerator = require('./generators/GeminiGenerator');
 
 module.exports = {
   GeminiGenerator,
+  MODELS: GeminiGenerator.MODELS,
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genmix",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "AI-powered image generator using Google Gemini API. Supports image generation from text prompts and image modification with reference images.",
   "license": "MIT",
   "author": "Martin Clasen",
@@ -8,6 +8,7 @@
     "nano",
     "banana",
     "pro",
+    "flash",
     "image-generator",
     "google-gemini",
     "gemini-api",
@@ -24,7 +25,7 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "axios": "^1.13.2",
+    "axios": "^1.13.6",
     "hash-factory": "^1.1.2",
     "sharp": "^0.33.5"
   }

package/skills/genmix/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: genmix
+description: AI-powered image generator using Google Gemini API. Use this skill when the user asks to generate an image from text, modify an existing image with a reference, apply style transfer, or create an image based on a prompt.
+---
+
+# GenMix Skill
+
+# Instructions
+
+### Step 1: Install GenMix
+If GenMix is not already installed in the project, install it:
+```bash
+npm install genmix
+```
+Ensure `GEMINI_API_KEY` is set in the `.env` file.
+
+### Step 2: Write the Generation Script
+Write a Node.js script to use GenMix based on the user's request.
+
+Example for generating a new image:
+```javascript
+import { GeminiGenerator } from 'genmix';
+
+const generator = new GeminiGenerator();
+await generator.generate('Your prompt here', { quality: '2K' });
+await generator.save({ directory: './output' });
+```
+
+Example for modifying an image with a reference:
+```javascript
+import { GeminiGenerator } from 'genmix';
+
+const generator = new GeminiGenerator();
+await generator
+  .addReference('./path/to/reference.jpg', 'Description of reference')
+  .generate('Your modification prompt here', { quality: '2K' });
+await generator.save({ directory: './output' });
+```
+
+### Step 3: Execute the script
+Run the script using Node.js to generate the image.
+
+## Examples
+
+**Example 1: Generate a futuristic city**
+User says: "Generate an image of a futuristic city"
+Actions: Create a script using GenMix to generate the image with the prompt "A futuristic city with flying cars, cyberpunk style", run the script, and save the output.
+
+**Example 2: Modify an image**
+User says: "Make this portrait look like a watercolor painting"
+Actions: Create a script using GenMix, add the portrait as a reference image, use the prompt "Transform this photo into a watercolor painting", run the script, and save the output.