genmix 1.1.5 → 1.2.2

package/README.md

@@ -1,6 +1,6 @@
 # 🎨 GenMix
 
-AI-powered image generator using Google Gemini API. Supports image generation from text prompts and image modification with reference images.
+AI-powered image generator supporting Google Gemini and Fal Nano Banana 2. Supports image generation from text prompts and image modification with reference images (Gemini).
 
 ## Features ✨
 
@@ -30,8 +30,11 @@ Create a `.env` file in your project root:
 
 ```env
 GEMINI_API_KEY=your_api_key_here
+FAL_API_KEY=your_fal_api_key_here
 ```
 
+`GEMINI_API_KEY` is used with provider `gemini` and `FAL_API_KEY` is used with provider `fal`.
+
 ## Basic Usage
 
 ### The Power of GenMix: Multiple References & Chainable API
@@ -51,6 +54,26 @@ const result = await generator
 await generator.save({ filename: 'composite-result' });
 ```
 
+### Provider Selection (Gemini or Fal)
+
+```javascript
+import { GeminiGenerator, FalGenerator } from 'genmix';
+
+const gemini = new GeminiGenerator({ apiKey: process.env.GEMINI_API_KEY });
+const fal = new FalGenerator({ apiKey: process.env.FAL_API_KEY });
+
+await gemini.flash().generate('A cinematic portrait with dramatic lighting');
+await fal.generate('A cinematic portrait with dramatic lighting', {
+  numberOfImages: 1,
+  quality: '1K',
+  aspectRatio: '1:1'
+});
+```
+
+Fal models available in this integration:
+- `flash` (or `banana2`) -> `fal-ai/nano-banana-2/edit` (image-to-image editing)
+- `pro` (or `banana-pro`) -> `fal-ai/nano-banana-pro/edit` (image-to-image editing)
+
 ### Model Selection
 
 You can easily switch between the Pro and Flash models using chainable methods:
@@ -134,6 +157,13 @@ new GeminiGenerator({
 })
 ```
 
+```javascript
+new FalGenerator({
+  apiKey: string,           // Your Fal API key (required)
+  modelId: string           // Optional: FalGenerator.MODELS.BANANA_2 or BANANA_PRO_EDIT
+})
+```
+
 ### Model Selection Methods
 
 ```javascript
@@ -142,6 +172,15 @@ generator.flash()  // Switches to the gemini-3.1-flash-image-preview model
 ```
 Both methods are chainable and return the generator instance.
 
+Fal generator model methods:
+
+```javascript
+fal.banana2()   // fal-ai/nano-banana-2/edit (image editing)
+fal.bananaPro() // fal-ai/nano-banana-pro/edit (image editing)
+fal.pro()       // alias of bananaPro()
+fal.flash()     // alias of banana2()
+```
+
 ### Reference Methods
 
 You can also use chainable methods to add one or multiple reference images before calling `generate()`:
@@ -151,6 +190,8 @@ generator.addReference(image, description) // Adds a reference image (path, URL,
 generator.clearReferences()                // Removes all queued reference images
 ```
 
+For `fal` (`flash` and `pro`), references can be URL, data URI, local file path, or Buffer.
+
 ### generate() Method
 
 ```javascript
@@ -323,7 +364,8 @@ try {
 genmix/
 └── generators/
 │   ├── BaseGenerator.js      # Base class with utilities
-│   └── GeminiGenerator.js    # Gemini API implementation
+│   ├── GeminiGenerator.js    # Gemini API implementation
+│   └── FalGenerator.js       # Fal Nano Banana 2 implementation
 ├── demo/
 │   ├── example.js                # Basic examples
 │   └── example-translation.js    # Translate image
@@ -376,8 +418,8 @@ genmix --config
 ```
 
 API key resolution order in CLI:
-1. `GEMINI_API_KEY` environment variable
-2. Saved config (`~/.genmix/config.json`)
+1. Provider-specific environment variable (`GEMINI_API_KEY` or `FAL_API_KEY`)
+2. Saved config (`~/.genmix/config.json`) using `geminiApiKey`/`apiKey` or `falApiKey`
 3. Interactive prompt (then persisted)
 
 ### Basic CLI commands
@@ -391,6 +433,12 @@ genmix "A futuristic city with flying cars, cyberpunk style"
 
 # Generate multiple images
 genmix "A cozy cabin in winter" -n 2 -q 2K -r 16:9 -m flash
+
+# Use Fal Nano Banana 2 edit (flash) with reference
+genmix "Restyle this room with warm sunset mood" --provider fal -m flash --ref "./room.jpg" -n 2 -q 2K -r 16:9
+
+# Use Fal Nano Banana Pro (edit) with reference
+genmix "make this scene cinematic" --provider fal -m banana-pro --ref "https://example.com/input.png"
 ```
 
 ### Output file path or directory
@@ -438,6 +486,11 @@ genmix "Restyle this room" --ref "./room.jpg:keep composition and camera angle"
 genmix "Create product ad scene" \
   --ref "./product.png:use as main subject" \
   --ref "./bg.jpg:use as background mood"
+
+# References for fal models (URL, data URI, or local path)
+genmix "Edit this image for a magazine look" \
+  --provider fal -m flash \
+  --ref "./photo.png"
 ```
 
 ### CLI options
@@ -445,13 +498,15 @@ genmix "Create product ad scene" \
 ```text
 -n, --number <N>          Number of images (default: 1)
 -q, --quality <1K|2K|4K>  Image quality (default: 1K)
--r, --ratio <ratio>       Aspect ratio (default: 1:1)
--m, --model <pro|flash>   Model (default: flash)
+-p, --provider <gemini|fal> Provider (default: gemini)
+-r, --ratio <ratio>       Aspect ratio (default: 1:1 for gemini, auto for fal)
+-m, --model <...>         gemini: pro|flash (default: flash)
+                          fal: pro|flash (aliases: banana-pro|banana2|2, default: flash)
 -o, --output <path>       Output directory or full output file path
 -f, --format <format>     Output format when output is a directory (default: jpg)
 --width <px>              Final output width in pixels (requires --height)
 --height <px>             Final output height in pixels (requires --width)
---ref <path:text>         Reference image, optional description after ":"
+--ref <path[:text]>       Reference image (path/URL/data URI); for URL descriptions use URL::description
 --no-sharp                Save raw model bytes without Sharp conversion (disables resizing)
 --config                  Set/update persisted API key
 --help                    Show help
@@ -461,6 +516,8 @@ genmix "Create product ad scene" \
 
 - [Code Examples](./demo/)
 - [Google Gemini API Documentation](https://ai.google.dev/)
+- [Fal Nano Banana 2 Edit Documentation](https://fal.ai/models/fal-ai/nano-banana-2/edit/api)
+- [Fal Nano Banana Pro Edit Documentation](https://fal.ai/models/fal-ai/nano-banana-pro/edit/api)
 
 ## License
 

package/cli.js

@@ -5,6 +5,7 @@ const path = require('path');
 const os = require('os');
 const readline = require('readline');
 const GeminiGenerator = require('./generators/GeminiGenerator');
+const FalGenerator = require('./generators/FalGenerator');
 
 const CONFIG_DIR = path.join(os.homedir(), '.genmix');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
@@ -72,6 +73,14 @@ async function promptApiKey() {
     return apiKey;
 }
 
+async function promptFalApiKey() {
+    const apiKey = (await promptQuestion('Enter your Fal API key: ')).trim();
+    if (!apiKey) {
+        throw new Error('API key cannot be empty.');
+    }
+    return apiKey;
+}
+
 function printHelp() {
     console.log(`
 Usage:
@@ -80,21 +89,27 @@ Usage:
   genmix --help
 
 Options:
+  -p, --provider <gemini|fal> Provider (default: gemini)
   -n, --number <N>        Number of images (default: 1)
   -q, --quality <1K|2K|4K> Image quality (default: 1K)
-  -r, --ratio <ratio>     Aspect ratio (default: 1:1)
+  -r, --ratio <ratio>     Aspect ratio (default: 1:1 for gemini, auto for fal)
   --width <px>            Final output width in pixels (requires --height)
   --height <px>           Final output height in pixels (requires --width)
-  -m, --model <pro|flash> Model (default: flash)
+  -m, --model <...>       Model by provider:
+                          gemini -> pro|flash (default: flash)
+                          fal -> pro|flash (aliases: banana-pro|banana2|2, default: flash)
   -o, --output <path>     Output directory OR full output file path
   -f, --format <format>   Output format when output is a directory (default: jpg)
   --no-sharp              Save raw model bytes without Sharp conversion
-  --ref <path:text>       Reference image; optional description after ":" (repeatable)
+  --ref <path[:text]>     Reference image; optional description after ":" (repeatable)
+                          For URLs, use plain URL or URL::description
   --help                  Show this help message
   --config                Set or update persisted API key
 
 Examples:
   genmix "cyberpunk city at night"
+  genmix "restyle this room" --provider fal --ref ./room.jpg
+  genmix "edit this image with sunset light" --provider fal -m banana-pro --ref "https://example.com/photo.jpg"
   genmix "logo in watercolor style" -n 2 -q 2K -o ./output
   genmix "app icon" -q 4K --width 400 --height 400 --output ./renders/icon.png
   genmix "new version of this room" --ref room.jpg:"keep composition"
@@ -103,13 +118,26 @@ Examples:
 }
 
 function parseRefValue(value) {
-    const firstColonIndex = value.indexOf(':');
+    const raw = value.trim();
+    const explicitSeparatorIndex = raw.indexOf('::');
+    if (explicitSeparatorIndex !== -1) {
+        return {
+            imagePath: raw.slice(0, explicitSeparatorIndex).trim(),
+            description: raw.slice(explicitSeparatorIndex + 2).trim()
+        };
+    }
+
+    if (/^https?:\/\//i.test(raw)) {
+        return { imagePath: raw, description: '' };
+    }
+
+    const firstColonIndex = raw.indexOf(':');
     if (firstColonIndex === -1) {
-        return { imagePath: value.trim(), description: '' };
+        return { imagePath: raw, description: '' };
     }
 
-    const imagePath = value.slice(0, firstColonIndex).trim();
-    const description = value.slice(firstColonIndex + 1).trim();
+    const imagePath = raw.slice(0, firstColonIndex).trim();
+    const description = raw.slice(firstColonIndex + 1).trim();
     return { imagePath, description };
 }
 
@@ -117,11 +145,13 @@ function parseArgs(argv) {
     const parsed = {
         promptParts: [],
         references: [],
+        provider: 'gemini',
         numberOfImages: 1,
         quality: '1K',
         aspectRatio: null,
         aspectRatioWasProvided: false,
-        model: 'flash',
+        model: null,
+        modelWasProvided: false,
         output: '.',
         format: 'jpg',
         targetWidth: null,
@@ -159,6 +189,13 @@ function parseArgs(argv) {
             continue;
         }
 
+        if (arg === '-p' || arg === '--provider') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.provider = String(next).toLowerCase();
+            i += 1;
+            continue;
+        }
+
         if (arg === '-r' || arg === '--ratio') {
             if (!next) throw new Error(`${arg} requires a value.`);
             parsed.aspectRatio = next;
@@ -184,6 +221,7 @@ function parseArgs(argv) {
         if (arg === '-m' || arg === '--model') {
             if (!next) throw new Error(`${arg} requires a value.`);
             parsed.model = String(next).toLowerCase();
+            parsed.modelWasProvided = true;
             i += 1;
             continue;
         }
@@ -235,8 +273,24 @@ function parseArgs(argv) {
     }
     parsed.quality = quality;
 
-    if (!['flash', 'pro'].includes(parsed.model)) {
-        throw new Error('Model must be "flash" or "pro".');
+    if (!['gemini', 'fal'].includes(parsed.provider)) {
+        throw new Error('Provider must be "gemini" or "fal".');
+    }
+
+    if (parsed.provider === 'gemini' && !parsed.modelWasProvided) {
+        parsed.model = 'flash';
+    }
+
+    if (parsed.provider === 'fal' && !parsed.modelWasProvided) {
+        parsed.model = 'flash';
+    }
+
+    if (parsed.provider === 'gemini' && !['flash', 'pro'].includes(parsed.model)) {
+        throw new Error('Model must be "flash" or "pro" when provider is "gemini".');
+    }
+
+    if (parsed.provider === 'fal' && !['flash', 'pro', 'banana2', 'banana-pro', '2'].includes(parsed.model)) {
+        throw new Error('Model must be "flash" or "pro" when provider is "fal" (aliases: banana2, banana-pro, 2).');
     }
 
     const hasOnlyOneDimension = (parsed.targetWidth === null) !== (parsed.targetHeight === null);
@@ -259,7 +313,7 @@ function parseArgs(argv) {
     }
 
     if (!parsed.aspectRatioWasProvided && !hasTargetDimensions) {
-        parsed.aspectRatio = '1:1';
+        parsed.aspectRatio = parsed.provider === 'fal' ? 'auto' : '1:1';
     }
 
     for (const ref of parsed.references) {
@@ -292,48 +346,95 @@ function resolveOutput(outputArg, format) {
     };
 }
 
-async function ensureApiKey() {
+async function ensureApiKey(provider = 'gemini') {
     const config = loadConfig();
+
+    if (provider === 'fal') {
+        const envApiKey = process.env.FAL_API_KEY;
+        if (envApiKey && envApiKey.trim()) {
+            return envApiKey.trim();
+        }
+        if (config.falApiKey && config.falApiKey.trim()) {
+            return config.falApiKey.trim();
+        }
+
+        info('No Fal API key found. Let us configure it now.');
+        const newApiKey = await promptFalApiKey();
+        saveConfig({ ...config, falApiKey: newApiKey });
+        success(`Fal API key saved to ${CONFIG_PATH}`);
+        return newApiKey;
+    }
+
     const envApiKey = process.env.GEMINI_API_KEY;
     if (envApiKey && envApiKey.trim()) {
         return envApiKey.trim();
     }
+    if (config.geminiApiKey && config.geminiApiKey.trim()) {
+        return config.geminiApiKey.trim();
+    }
     if (config.apiKey && config.apiKey.trim()) {
         return config.apiKey.trim();
     }
 
-    info('No API key found. Let us configure it now.');
+    info('No Gemini API key found. Let us configure it now.');
     const newApiKey = await promptApiKey();
-    saveConfig({ ...config, apiKey: newApiKey });
-    success(`API key saved to ${CONFIG_PATH}`);
+    saveConfig({ ...config, apiKey: newApiKey, geminiApiKey: newApiKey });
+    success(`Gemini API key saved to ${CONFIG_PATH}`);
     return newApiKey;
 }
 
-async function runConfigCommand() {
+async function runConfigCommand(provider) {
     const existing = loadConfig();
-    if (existing.apiKey) {
-        info(`Existing API key found in ${CONFIG_PATH}.`);
+    if (provider === 'fal') {
+        if (existing.falApiKey) {
+            info(`Existing Fal API key found in ${CONFIG_PATH}.`);
+        } else {
+            info('No saved Fal API key found.');
+        }
+
+        const newApiKey = await promptFalApiKey();
+        saveConfig({ ...existing, falApiKey: newApiKey });
+        success(`Fal API key saved to ${CONFIG_PATH}`);
+        return;
+    }
+
+    if (existing.apiKey || existing.geminiApiKey) {
+        info(`Existing Gemini API key found in ${CONFIG_PATH}.`);
     } else {
-        info('No saved API key found.');
+        info('No saved Gemini API key found.');
     }
 
     const newApiKey = await promptApiKey();
-    saveConfig({ ...existing, apiKey: newApiKey });
-    success(`API key saved to ${CONFIG_PATH}`);
+    saveConfig({ ...existing, apiKey: newApiKey, geminiApiKey: newApiKey });
+    success(`Gemini API key saved to ${CONFIG_PATH}`);
 }
 
 async function runGeneration(args) {
-    const apiKey = await ensureApiKey();
-    const generator = new GeminiGenerator({ apiKey });
-
-    if (args.model === 'pro') {
+    const apiKey = await ensureApiKey(args.provider);
+    const generator = args.provider === 'fal'
+        ? new FalGenerator({ apiKey })
+        : new GeminiGenerator({ apiKey });
+
+    if (args.provider === 'gemini') {
+        if (args.model === 'pro') {
+            generator.pro();
+        } else {
+            generator.flash();
+        }
+    } else if (args.model === 'banana-pro' || args.model === 'pro') {
         generator.pro();
     } else {
         generator.flash();
     }
 
+    if (args.provider === 'fal' && args.references.length === 0) {
+        throw new Error('Fal edit models require at least one --ref input image.');
+    }
+
     for (const ref of args.references) {
-        generator.addReference(ref.imagePath, ref.description);
+        if (typeof generator.addReference === 'function') {
+            generator.addReference(ref.imagePath, ref.description);
+        }
     }
 
     info('Generating image(s)...');
@@ -375,7 +476,7 @@ async function main() {
         }
 
         if (args.runConfig) {
-            await runConfigCommand();
+            await runConfigCommand(args.provider);
             return;
         }
 

package/demo/example-fal.js

@@ -0,0 +1,82 @@
+try { process.loadEnvFile(); } catch (error) { }
+import { FalGenerator } from '../index.js';
+
+async function runFalFlashExample() {
+    console.log('\n=== Fal Example 1: Nano Banana 2 (flash) ===\n');
+
+    const referenceUrl = process.env.FAL_DEMO_IMAGE_URL;
+    if (!referenceUrl) {
+        console.log('ℹ️  Skipping flash edit example: set FAL_DEMO_IMAGE_URL in your .env with an image URL.');
+        return;
+    }
+
+    const generator = new FalGenerator();
+    generator.flash().addReference(referenceUrl, 'use as base image');
+
+    const result = await generator.generate(
+        'A futuristic city skyline at dusk, cinematic lighting, ultra detailed',
+        {
+            numberOfImages: 1,
+            quality: '1K',
+            aspectRatio: '16:9'
+        }
+    );
+
+    if (result.images && result.images.length > 0) {
+        const saved = await generator.save({
+            directory: import.meta.dirname,
+            filename: 'fal-flash-example'
+        });
+        console.log(`✅ Saved flash result: ${saved[0]}`);
+    } else {
+        console.log('⚠️  No images generated for flash example.');
+    }
+}
+
+async function runFalProExample() {
+    console.log('\n=== Fal Example 2: Nano Banana Pro (edit) ===\n');
+
+    const referenceUrl = process.env.FAL_DEMO_IMAGE_URL;
+    if (!referenceUrl) {
+        console.log('ℹ️  Skipping pro edit example: set FAL_DEMO_IMAGE_URL in your .env with an image URL.');
+        return;
+    }
+
+    const generator = new FalGenerator();
+    generator
+        .pro()
+        .addReference(referenceUrl, 'use as base image');
+
+    const result = await generator.generate(
+        'Turn this into a cinematic editorial shot with warm golden-hour color grading',
+        {
+            numberOfImages: 1,
+            quality: '1K'
+        }
+    );
+
+    if (result.images && result.images.length > 0) {
+        const saved = await generator.save({
+            directory: import.meta.dirname,
+            filename: 'fal-pro-edit-example'
+        });
+        console.log(`✅ Saved pro edit result: ${saved[0]}`);
+    } else {
+        console.log('⚠️  No images generated for pro edit example.');
+    }
+}
+
+async function main() {
+    try {
+        await runFalFlashExample();
+        await runFalProExample();
+        console.log('\n🎉 Fal examples completed!\n');
+    } catch (error) {
+        console.error('❌ Error:', error.message);
+        if (error.message.includes('API Key')) {
+            console.error('\n💡 Tip: Make sure you have FAL_API_KEY in your .env file');
+        }
+    }
+}
+
+main();

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/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.1.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,6 +11,9 @@
     "flash",
     "image-generator",
     "google-gemini",
+    "fal-ai",
+    "nano-banana-2",
+    "nano-banana-pro",
     "gemini-api",
     "text-to-image",
     "image-modification",