genmix 1.0.5 → 1.2.2

package/generators/BaseGenerator.js

@@ -29,9 +29,13 @@ class BaseGenerator {
      * @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', formatOptions = null} = {}) {
+    async save({directory = '.', filename = null, extension = 'jpg', formatOptions = null, useSharp = true} = {}) {
         const targetImages = this.lastGeneration?.images;
         const targetPrompt = this.lastGeneration?.prompt;
+        const inheritedFormatOptions = this.lastGeneration?.formatOptions || null;
+        const effectiveFormatOptions = formatOptions
+            ? { ...(inheritedFormatOptions || {}), ...formatOptions }
+            : inheritedFormatOptions;
 
         if (!targetImages || !Array.isArray(targetImages) || targetImages.length === 0) {
             console.warn('No images to save.');
@@ -48,8 +52,8 @@ class BaseGenerator {
         }
 
         // Use format from formatOptions if provided, otherwise use extension
-        if (formatOptions && formatOptions.format) {
-            extension = formatOptions.format;
+        if (effectiveFormatOptions && effectiveFormatOptions.format) {
+            extension = effectiveFormatOptions.format;
         }
 
         // Normalize extension
@@ -69,32 +73,43 @@ class BaseGenerator {
         
         for (let index = 0; index < targetImages.length; index++) {
             const imgData = targetImages[index];
-            const base64Data = imgData.replace(/^data:image\/\w+;base64,/, "");
+            const mimeMatch = imgData.match(/^data:image\/([a-zA-Z0-9.+-]+);base64,/);
+            const sourceFormat = mimeMatch ? mimeMatch[1].toLowerCase() : null;
+            const normalizedSourceFormat = sourceFormat === 'jpeg' ? 'jpg' : sourceFormat;
+            const base64Data = imgData.replace(/^data:image\/[a-zA-Z0-9.+-]+;base64,/, "");
             const buffer = Buffer.from(base64Data, 'base64');
 
+            const effectiveExtension = useSharp ? fileExtension : (normalizedSourceFormat || fileExtension);
+
             let fileName;
             if (filename) {
                 // Use custom filename, add index if multiple images
                 if (targetImages.length > 1) {
-                    fileName = `${filename}_${index}.${fileExtension}`;
+                    fileName = `${filename}_${index}.${effectiveExtension}`;
                 } else {
-                    fileName = `${filename}.${fileExtension}`;
+                    fileName = `${filename}.${effectiveExtension}`;
                 }
             } else {
                 // Use hash-based filename
                 const hash = this.generateHash(targetPrompt + '_' + index);
-                fileName = `${hash}.${fileExtension}`;
+                fileName = `${hash}.${effectiveExtension}`;
             }
             
             const outputPath = path.join(directory, fileName);
 
+            if (!useSharp) {
+                fs.writeFileSync(outputPath, buffer);
+                savedPaths.push(outputPath);
+                continue;
+            }
+
             // Convert image format using sharp
             try {
                 let sharpInstance = sharp(buffer);
                 
                 // Resize if dimensions are specified in formatOptions
-                if (formatOptions && formatOptions.width && formatOptions.height) {
-                    sharpInstance = sharpInstance.resize(formatOptions.width, formatOptions.height, {
+                if (effectiveFormatOptions && effectiveFormatOptions.width && effectiveFormatOptions.height) {
+                    sharpInstance = sharpInstance.resize(effectiveFormatOptions.width, effectiveFormatOptions.height, {
                         fit: 'fill'
                     });
                 }
@@ -102,29 +117,29 @@ class BaseGenerator {
                 // Build format-specific options
                 const sharpFormatOptions = {};
                 
-                if (formatOptions) {
-                    if (sharpFormat === 'jpg' && formatOptions.quality) {
-                        sharpFormatOptions.quality = formatOptions.quality;
+                if (effectiveFormatOptions) {
+                    if (sharpFormat === 'jpg' && effectiveFormatOptions.quality) {
+                        sharpFormatOptions.quality = effectiveFormatOptions.quality;
                     } else if (sharpFormat === 'png') {
-                        if (formatOptions.compressionLevel !== undefined) {
-                            sharpFormatOptions.compressionLevel = formatOptions.compressionLevel;
+                        if (effectiveFormatOptions.compressionLevel !== undefined) {
+                            sharpFormatOptions.compressionLevel = effectiveFormatOptions.compressionLevel;
                         }
-                        if (formatOptions.quality !== undefined) {
-                            sharpFormatOptions.quality = formatOptions.quality;
+                        if (effectiveFormatOptions.quality !== undefined) {
+                            sharpFormatOptions.quality = effectiveFormatOptions.quality;
                         }
-                        if (formatOptions.effort !== undefined) {
-                            sharpFormatOptions.effort = formatOptions.effort;
+                        if (effectiveFormatOptions.effort !== undefined) {
+                            sharpFormatOptions.effort = effectiveFormatOptions.effort;
                         }
-                        if (formatOptions.palette) {
+                        if (effectiveFormatOptions.palette) {
                             sharpFormatOptions.palette = true;
                             // Add dithering for better quality with palette
                             sharpFormatOptions.dither = 1.0;
                         }
-                        if (formatOptions.colours) {
-                            sharpFormatOptions.colours = formatOptions.colours;
+                        if (effectiveFormatOptions.colours) {
+                            sharpFormatOptions.colours = effectiveFormatOptions.colours;
                         }
-                    } else if (sharpFormat === 'webp' && formatOptions.quality) {
-                        sharpFormatOptions.quality = formatOptions.quality;
+                    } else if (sharpFormat === 'webp' && effectiveFormatOptions.quality) {
+                        sharpFormatOptions.quality = effectiveFormatOptions.quality;
                     }
                 }
                 

package/generators/FalGenerator.js

@@ -0,0 +1,332 @@
+const axios = require('axios');
+const BaseGenerator = require('./BaseGenerator');
+const fs = require('fs');
+const path = require('path');
+
+class FalGenerator extends BaseGenerator {
+    static MODELS = {
+        BANANA_2: 'fal-ai/nano-banana-2/edit',
+        BANANA_PRO_EDIT: 'fal-ai/nano-banana-pro/edit'
+    };
+
+    static SUPPORTED_ASPECT_RATIOS_BY_MODEL = {
+        [FalGenerator.MODELS.BANANA_2]: new Set([
+            'auto',
+            '21:9',
+            '16:9',
+            '3:2',
+            '4:3',
+            '5:4',
+            '1:1',
+            '4:5',
+            '3:4',
+            '2:3',
+            '9:16',
+            '4:1',
+            '1:4',
+            '8:1',
+            '1:8'
+        ]),
+        [FalGenerator.MODELS.BANANA_PRO_EDIT]: new Set([
+            'auto',
+            '21:9',
+            '16:9',
+            '3:2',
+            '4:3',
+            '5:4',
+            '1:1',
+            '4:5',
+            '3:4',
+            '2:3',
+            '9:16'
+        ])
+    };
+
+    static SUPPORTED_RESOLUTIONS_BY_MODEL = {
+        [FalGenerator.MODELS.BANANA_2]: new Set(['0.5K', '1K', '2K', '4K']),
+        [FalGenerator.MODELS.BANANA_PRO_EDIT]: new Set(['1K', '2K', '4K'])
+    };
+
+    static COMMON_ASPECT_RATIOS = new Set([
+        'auto',
+        '21:9',
+        '16:9',
+        '3:2',
+        '4:3',
+        '5:4',
+        '1:1',
+        '4:5',
+        '3:4',
+        '2:3',
+        '9:16'
+    ]);
+
+    constructor(config = {}) {
+        super(config);
+        this.apiKey = config.apiKey || process.env.FAL_API_KEY;
+        if (!this.apiKey) {
+            throw new Error('API Key is required. Provide it in the constructor or set FAL_API_KEY environment variable.');
+        }
+        this.modelId = config.modelId || FalGenerator.MODELS.BANANA_2;
+        this.apiUrl = `https://fal.run/${this.modelId}`;
+        this.references = [];
+    }
+
+    banana2() {
+        this.modelId = FalGenerator.MODELS.BANANA_2;
+        this.apiUrl = `https://fal.run/${this.modelId}`;
+        return this;
+    }
+
+    bananaPro() {
+        this.modelId = FalGenerator.MODELS.BANANA_PRO_EDIT;
+        this.apiUrl = `https://fal.run/${this.modelId}`;
+        return this;
+    }
+
+    pro() {
+        return this.bananaPro();
+    }
+
+    flash() {
+        return this.banana2();
+    }
+
+    addReference(image, description = '') {
+        this.references.push({ image, description });
+        return this;
+    }
+
+    clearReferences() {
+        this.references = [];
+        return this;
+    }
+
+    _gcd(a, b) {
+        let x = Math.abs(a);
+        let y = Math.abs(b);
+        while (y !== 0) {
+            const t = y;
+            y = x % y;
+            x = t;
+        }
+        return x || 1;
+    }
+
+    _deriveAspectRatio(width, height) {
+        const divisor = this._gcd(width, height);
+        return `${width / divisor}:${height / divisor}`;
+    }
+
+    _normalizeGenerateOptions(options = {}) {
+        const normalized = { ...options };
+        const hasWidth = normalized.width !== undefined && normalized.width !== null;
+        const hasHeight = normalized.height !== undefined && normalized.height !== null;
+
+        if (hasWidth !== hasHeight) {
+            throw new Error('Both options.width and options.height are required together.');
+        }
+
+        if (hasWidth && hasHeight) {
+            const width = Number(normalized.width);
+            const height = Number(normalized.height);
+
+            if (!Number.isInteger(width) || width <= 0) {
+                throw new Error('options.width must be a positive integer.');
+            }
+            if (!Number.isInteger(height) || height <= 0) {
+                throw new Error('options.height must be a positive integer.');
+            }
+
+            const derivedRatio = this._deriveAspectRatio(width, height);
+            if (normalized.aspectRatio && normalized.aspectRatio !== derivedRatio) {
+                throw new Error(`Aspect ratio mismatch: options.aspectRatio ${normalized.aspectRatio} does not match options.width/options.height (${derivedRatio}).`);
+            }
+
+            normalized.width = width;
+            normalized.height = height;
+            normalized.aspectRatio = derivedRatio;
+        }
+
+        const supportedRatios = FalGenerator.SUPPORTED_ASPECT_RATIOS_BY_MODEL[this.modelId] || FalGenerator.COMMON_ASPECT_RATIOS;
+        if (normalized.aspectRatio && !supportedRatios.has(normalized.aspectRatio)) {
+            if (hasWidth && hasHeight) {
+                normalized.aspectRatio = 'auto';
+            } else {
+                throw new Error(`Unsupported aspect ratio for Fal provider: ${normalized.aspectRatio}.`);
+            }
+        }
+
+        return normalized;
+    }
+
+    _mapQualityToResolution(quality) {
+        const mapped = String(quality || '1K').toUpperCase();
+        const supportedResolutions = FalGenerator.SUPPORTED_RESOLUTIONS_BY_MODEL[this.modelId] || new Set(['1K', '2K', '4K']);
+        if (!supportedResolutions.has(mapped)) {
+            throw new Error(`options.quality must be one of: ${Array.from(supportedResolutions).join(', ')}.`);
+        }
+        return mapped;
+    }
+
+    _isHttpUrl(value) {
+        return typeof value === 'string' && /^https?:\/\//i.test(value.trim());
+    }
+
+    _isDataUri(value) {
+        return typeof value === 'string' && /^data:image\/[a-zA-Z0-9.+-]+;base64,/.test(value.trim());
+    }
+
+    _detectMimeTypeFromPath(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        const mimeTypes = {
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.webp': 'image/webp',
+            '.gif': 'image/gif',
+            '.bmp': 'image/bmp',
+            '.tif': 'image/tiff',
+            '.tiff': 'image/tiff',
+            '.avif': 'image/avif'
+        };
+        return mimeTypes[ext] || 'image/png';
+    }
+
+    _toDataUriFromBuffer(buffer, mimeType = 'image/png') {
+        return `data:${mimeType};base64,${buffer.toString('base64')}`;
+    }
+
+    async _normalizeImageReference(value) {
+        if (Buffer.isBuffer(value)) {
+            return this._toDataUriFromBuffer(value, 'image/png');
+        }
+
+        if (typeof value !== 'string') {
+            throw new Error('Fal references must be URL, data URI, local file path, or Buffer.');
+        }
+
+        const trimmed = value.trim();
+        if (!trimmed) {
+            throw new Error('Fal reference cannot be empty.');
+        }
+
+        if (this._isHttpUrl(trimmed) || this._isDataUri(trimmed)) {
+            return trimmed;
+        }
+
+        if (!fs.existsSync(trimmed)) {
+            throw new Error(`Fal reference file not found: ${trimmed}`);
+        }
+
+        const fileBuffer = fs.readFileSync(trimmed);
+        const mimeType = this._detectMimeTypeFromPath(trimmed);
+        return this._toDataUriFromBuffer(fileBuffer, mimeType);
+    }
+
+    async _collectImageUrls(options = {}) {
+        const rawReferences = [];
+
+        if (Array.isArray(options.imageUrls)) {
+            for (const value of options.imageUrls) {
+                if ((typeof value === 'string' && value.trim()) || Buffer.isBuffer(value)) {
+                    rawReferences.push(value);
+                }
+            }
+        }
+
+        if ((typeof options.referenceImage === 'string' && options.referenceImage.trim()) || Buffer.isBuffer(options.referenceImage)) {
+            rawReferences.push(options.referenceImage);
+        }
+
+        for (const ref of this.references) {
+            if ((typeof ref.image === 'string' && ref.image.trim()) || Buffer.isBuffer(ref.image)) {
+                rawReferences.push(ref.image);
+            }
+        }
+
+        const normalizedUrls = [];
+        for (const reference of rawReferences) {
+            normalizedUrls.push(await this._normalizeImageReference(reference));
+        }
+
+        const uniqueUrls = Array.from(new Set(normalizedUrls));
+        return uniqueUrls;
+    }
+
+    async generate(prompt, options = {}) {
+        if (!prompt || !String(prompt).trim()) {
+            throw new Error('Prompt is required.');
+        }
+
+        const normalizedOptions = this._normalizeGenerateOptions(options);
+        const numberOfImages = normalizedOptions.numberOfImages || 1;
+
+        if (!Number.isInteger(numberOfImages) || numberOfImages < 1 || numberOfImages > 4) {
+            throw new Error('options.numberOfImages must be an integer between 1 and 4 for Fal Nano Banana models.');
+        }
+
+        const payload = {
+            prompt: String(prompt).trim(),
+            num_images: numberOfImages,
+            resolution: this._mapQualityToResolution(normalizedOptions.quality),
+            aspect_ratio: normalizedOptions.aspectRatio || 'auto'
+        };
+
+        const imageUrls = await this._collectImageUrls(normalizedOptions);
+        if (imageUrls.length === 0) {
+            throw new Error('Fal Nano Banana edit models require at least one reference image. Use addReference() or options.referenceImage.');
+        }
+        payload.image_urls = imageUrls;
+
+        try {
+            const response = await axios.post(this.apiUrl, payload, {
+                headers: {
+                    Authorization: `Key ${this.apiKey}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+
+            const result = await this.processResponse(response.data);
+            this.lastGeneration = {
+                prompt: String(prompt).trim(),
+                images: result.images,
+                text: result.text,
+                raw: result.raw,
+                formatOptions: normalizedOptions.width && normalizedOptions.height
+                    ? { width: normalizedOptions.width, height: normalizedOptions.height }
+                    : null
+            };
+            this.references = [];
+            return result;
+        } catch (error) {
+            const apiError = error.response?.data;
+            const message = apiError?.detail || apiError?.error || error.message;
+            throw new Error(`Fal API Error: ${message}`);
+        }
+    }
+
+    async processResponse(data) {
+        const imageEntries = Array.isArray(data?.images) ? data.images : [];
+        const images = [];
+
+        for (const entry of imageEntries) {
+            if (!entry || !entry.url) {
+                continue;
+            }
+
+            const mediaResponse = await axios.get(entry.url, { responseType: 'arraybuffer' });
+            const contentType = entry.content_type || mediaResponse.headers['content-type'] || 'image/png';
+            const base64 = Buffer.from(mediaResponse.data).toString('base64');
+            images.push(`data:${contentType};base64,${base64}`);
+        }
+
+        return {
+            images,
+            text: data?.description || '',
+            raw: data
+        };
+    }
+}
+
+module.exports = FalGenerator;

package/generators/GeminiGenerator.js

@@ -67,6 +67,55 @@ class GeminiGenerator extends BaseGenerator {
         return this;
     }
 
+    _gcd(a, b) {
+        let x = Math.abs(a);
+        let y = Math.abs(b);
+        while (y !== 0) {
+            const t = y;
+            y = x % y;
+            x = t;
+        }
+        return x || 1;
+    }
+
+    _deriveAspectRatio(width, height) {
+        const divisor = this._gcd(width, height);
+        return `${width / divisor}:${height / divisor}`;
+    }
+
+    _normalizeGenerateOptions(options = {}) {
+        const normalizedOptions = { ...options };
+        const hasWidth = normalizedOptions.width !== undefined && normalizedOptions.width !== null;
+        const hasHeight = normalizedOptions.height !== undefined && normalizedOptions.height !== null;
+
+        if (hasWidth !== hasHeight) {
+            throw new Error('Both options.width and options.height are required together.');
+        }
+
+        if (hasWidth && hasHeight) {
+            const width = Number(normalizedOptions.width);
+            const height = Number(normalizedOptions.height);
+
+            if (!Number.isInteger(width) || width <= 0) {
+                throw new Error('options.width must be a positive integer.');
+            }
+            if (!Number.isInteger(height) || height <= 0) {
+                throw new Error('options.height must be a positive integer.');
+            }
+
+            const derivedRatio = this._deriveAspectRatio(width, height);
+            if (normalizedOptions.aspectRatio && normalizedOptions.aspectRatio !== derivedRatio) {
+                throw new Error(`Aspect ratio mismatch: options.aspectRatio ${normalizedOptions.aspectRatio} does not match options.width/options.height (${derivedRatio}).`);
+            }
+
+            normalizedOptions.aspectRatio = derivedRatio;
+            normalizedOptions.width = width;
+            normalizedOptions.height = height;
+        }
+
+        return normalizedOptions;
+    }
+
     /**
      * @param {string} prompt
      * @param {Object} [options]
@@ -74,19 +123,22 @@ class GeminiGenerator extends BaseGenerator {
      * @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.
+     * @param {number} [options.width] - Final output width in pixels (requires options.height)
+     * @param {number} [options.height] - Final output height in pixels (requires options.width)
      * @returns {Promise<{images: string[], text: string, raw: any}>}
      */
     async generate(prompt, options = {}) {
+        const normalizedOptions = this._normalizeGenerateOptions(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;
+        const numberOfImages = normalizedOptions.numberOfImages || 1;
 
         let result;
         if (numberOfImages > 1) {
-            result = await this.generateMultiple(prompt, numberOfImages, options);
+            result = await this.generateMultiple(prompt, numberOfImages, normalizedOptions);
         } else {
-            result = await this._generateSingleRequest(prompt, options);
+            result = await this._generateSingleRequest(prompt, normalizedOptions);
         }
 
         // Store result in state for saveImages()
@@ -94,7 +146,10 @@ class GeminiGenerator extends BaseGenerator {
             prompt: prompt,
             images: result.images,
             text: result.text,
-            raw: result.raw
+            raw: result.raw,
+            formatOptions: normalizedOptions.width && normalizedOptions.height
+                ? { width: normalizedOptions.width, height: normalizedOptions.height }
+                : null
         };
 
         this.references = [];

package/index.js

@@ -1,7 +1,10 @@
 const GeminiGenerator = require('./generators/GeminiGenerator');
+const FalGenerator = require('./generators/FalGenerator');
 
 module.exports = {
   GeminiGenerator,
+  FalGenerator,
   MODELS: GeminiGenerator.MODELS,
+  FAL_MODELS: FalGenerator.MODELS,
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "genmix",
-  "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.",
+  "version": "1.2.2",
+  "description": "AI-powered image generator supporting Google Gemini and Fal Nano Banana 2.",
   "license": "MIT",
   "author": "Martin Clasen",
   "keywords": [
@@ -11,16 +11,23 @@
     "flash",
     "image-generator",
     "google-gemini",
+    "fal-ai",
+    "nano-banana-2",
+    "nano-banana-pro",
     "gemini-api",
     "text-to-image",
     "image-modification",
     "style-transfer",
     "generative-ai",
     "genmix",
+    "cli",
     "clasen"
   ],
   "type": "commonjs",
   "main": "index.js",
+  "bin": {
+    "genmix": "./cli.js"
+  },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },