genmix 1.0.4 → 1.1.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
@@ -105,6 +166,8 @@ await generator.generate(prompt, options)
 | `options.numberOfImages` | number        | Number of images to generate                | 1       |
 | `options.quality`        | string        | Quality: '1K', '2K', '4K'                   | -       |
 | `options.aspectRatio`    | string        | Aspect ratio: '1:1', '16:9', '4:3', etc.    | -       |
+| `options.width`          | number        | Final output width in pixels (requires `height`) | -   |
+| `options.height`         | number        | Final output height in pixels (requires `width`) | -   |
 
 ### save() Method
 
@@ -142,6 +205,25 @@ await generator.save({ filename: 'my-image' });
 await generator.save();
 ```
 
+### Smart target size in library mode (non-CLI)
+
+You can request high generation quality and still force an exact final output size directly in `generate()`:
+
+```javascript
+const generator = new GeminiGenerator();
+
+await generator.generate('App icon, flat minimal style', {
+  quality: '4K', // generation quality (independent)
+  width: 400,
+  height: 400
+});
+
+// width/height resize is automatically applied on save()
+await generator.save({ filename: 'icon-400x400', extension: 'png' });
+```
+
+If you also pass `aspectRatio`, it must match the ratio derived from `width`/`height`.
+
 **Note:** 
 - When multiple images are generated and a custom filename is provided, they will be saved as `filename_0.jpg`, `filename_1.jpg`, etc.
 - The method uses Sharp for image conversion, supporting high-quality format conversion
@@ -190,7 +272,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(
@@ -269,6 +351,112 @@ genmix/
 
 4. **Result Caching**: Images are automatically saved with unique hash based on the prompt
 
+## CLI Usage
+
+### Global CLI Installation
+
+Install GenMix globally to use it from the command line:
+
+```bash
+npm install -g genmix
+```
+
+### First run and API key persistence
+
+If no API key is available, the CLI asks for it on first use and saves it to:
+
+```text
+~/.genmix/config.json
+```
+
+You can set or update it explicitly anytime:
+
+```bash
+genmix --config
+```
+
+API key resolution order in CLI:
+1. `GEMINI_API_KEY` environment variable
+2. Saved config (`~/.genmix/config.json`)
+3. Interactive prompt (then persisted)
+
+### Basic CLI commands
+
+```bash
+# Show help
+genmix --help
+
+# Generate from prompt
+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
+```
+
+### Output file path or directory
+
+`--output` accepts either:
+- a directory path, or
+- a full output file path (including filename + extension)
+
+```bash
+# Save to a directory (auto-generated hash filename)
+genmix "Watercolor fox logo" --output ./output
+
+# Save to exact file path and filename
+genmix "Watercolor fox logo" --output ./output/logo-fox.png
+```
+
+### Smart target size (independent from generation quality)
+
+You can ask the model for high generation quality (for example `4K`) and still force a final exact output size.
+
+When you pass target dimensions, GenMix CLI:
+1. Derives the generation ratio automatically (for example `400x400` -> `1:1`, `1920x1080` -> `16:9`)
+2. Generates using your selected quality (`1K`, `2K`, or `4K`)
+3. Resizes the final image to the exact dimensions you requested
+
+```bash
+# Ask for 4K quality, deliver exact 400x400 output
+genmix "app icon, flat minimal style" -q 4K --width 400 --height 400 --output ./output/icon.png
+```
+
+If you also pass `--ratio`, it must match the derived ratio from the target size.
+
+### References with optional text description
+
+Use `--ref <path:text>` to add reference images with optional guidance text:
+
+```bash
+# Reference path only
+genmix "Restyle this room" --ref ./room.jpg
+
+# Reference path + description
+genmix "Restyle this room" --ref "./room.jpg:keep composition and camera angle"
+
+# Multiple references with descriptions
+genmix "Create product ad scene" \
+  --ref "./product.png:use as main subject" \
+  --ref "./bg.jpg:use as background mood"
+```
+
+### CLI options
+
+```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)
+-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 ":"
+--no-sharp                Save raw model bytes without Sharp conversion (disables resizing)
+--config                  Set/update persisted API key
+--help                    Show help
+```
+
 ## Additional Resources
 
 - [Code Examples](./demo/)

package/cli.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const GeminiGenerator = require('./generators/GeminiGenerator');
+
+const CONFIG_DIR = path.join(os.homedir(), '.genmix');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const IMAGE_EXTENSIONS = new Set(['jpg', 'jpeg', 'png', 'webp', 'avif', 'tiff', 'tif', 'gif']);
+
+function color(code, message) {
+    return `\x1b[${code}m${message}\x1b[0m`;
+}
+
+function info(message) {
+    console.log(color('36', message));
+}
+
+function success(message) {
+    console.log(color('32', message));
+}
+
+function error(message) {
+    console.error(color('31', message));
+}
+
+function loadConfig() {
+    if (!fs.existsSync(CONFIG_PATH)) {
+        return {};
+    }
+
+    try {
+        const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+        if (!raw.trim()) {
+            return {};
+        }
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch (err) {
+        throw new Error(`Failed reading config at ${CONFIG_PATH}: ${err.message}`);
+    }
+}
+
+function saveConfig(config) {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf8');
+}
+
+function promptQuestion(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+
+async function promptApiKey() {
+    const apiKey = (await promptQuestion('Enter your Gemini API key: ')).trim();
+    if (!apiKey) {
+        throw new Error('API key cannot be empty.');
+    }
+    return apiKey;
+}
+
+function printHelp() {
+    console.log(`
+Usage:
+  genmix "prompt text" [options]
+  genmix --config
+  genmix --help
+
+Options:
+  -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)
+  --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)
+  -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)
+  --help                  Show this help message
+  --config                Set or update persisted API key
+
+Examples:
+  genmix "cyberpunk city at night"
+  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"
+  genmix "portrait variation" --ref subject.png --output ./renders/portrait.png
+`);
+}
+
+function parseRefValue(value) {
+    const firstColonIndex = value.indexOf(':');
+    if (firstColonIndex === -1) {
+        return { imagePath: value.trim(), description: '' };
+    }
+
+    const imagePath = value.slice(0, firstColonIndex).trim();
+    const description = value.slice(firstColonIndex + 1).trim();
+    return { imagePath, description };
+}
+
+function parseArgs(argv) {
+    const parsed = {
+        promptParts: [],
+        references: [],
+        numberOfImages: 1,
+        quality: '1K',
+        aspectRatio: null,
+        aspectRatioWasProvided: false,
+        model: 'flash',
+        output: '.',
+        format: 'jpg',
+        targetWidth: null,
+        targetHeight: null,
+        useSharp: true,
+        showHelp: false,
+        runConfig: false
+    };
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+
+        if (arg === '--help' || arg === '-h') {
+            parsed.showHelp = true;
+            continue;
+        }
+
+        if (arg === '--config') {
+            parsed.runConfig = true;
+            continue;
+        }
+
+        if (arg === '-n' || arg === '--number') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.numberOfImages = Number(next);
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-q' || arg === '--quality') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.quality = next;
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-r' || arg === '--ratio') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.aspectRatio = next;
+            parsed.aspectRatioWasProvided = true;
+            i += 1;
+            continue;
+        }
+
+        if (arg === '--width') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.targetWidth = Number(next);
+            i += 1;
+            continue;
+        }
+
+        if (arg === '--height') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.targetHeight = Number(next);
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-m' || arg === '--model') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.model = String(next).toLowerCase();
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-o' || arg === '--output') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.output = next;
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-f' || arg === '--format') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.format = String(next).replace(/^\./, '').toLowerCase();
+            i += 1;
+            continue;
+        }
+
+        if (arg === '--ref') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.references.push(parseRefValue(next));
+            i += 1;
+            continue;
+        }
+
+        if (arg === '--no-sharp') {
+            parsed.useSharp = false;
+            continue;
+        }
+
+        if (arg.startsWith('-')) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+
+        parsed.promptParts.push(arg);
+    }
+
+    if (!parsed.runConfig && !parsed.showHelp && parsed.promptParts.length === 0) {
+        throw new Error('Missing prompt text. Use genmix "your prompt".');
+    }
+
+    if (!Number.isInteger(parsed.numberOfImages) || parsed.numberOfImages <= 0) {
+        throw new Error('Number of images must be a positive integer.');
+    }
+
+    const quality = parsed.quality.toUpperCase();
+    if (!['1K', '2K', '4K'].includes(quality)) {
+        throw new Error('Quality must be one of: 1K, 2K, 4K.');
+    }
+    parsed.quality = quality;
+
+    if (!['flash', 'pro'].includes(parsed.model)) {
+        throw new Error('Model must be "flash" or "pro".');
+    }
+
+    const hasOnlyOneDimension = (parsed.targetWidth === null) !== (parsed.targetHeight === null);
+    if (hasOnlyOneDimension) {
+        throw new Error('Both --width and --height are required together.');
+    }
+
+    const hasTargetDimensions = parsed.targetWidth !== null && parsed.targetHeight !== null;
+    if (hasTargetDimensions) {
+        if (!Number.isInteger(parsed.targetWidth) || parsed.targetWidth <= 0) {
+            throw new Error('Width must be a positive integer.');
+        }
+        if (!Number.isInteger(parsed.targetHeight) || parsed.targetHeight <= 0) {
+            throw new Error('Height must be a positive integer.');
+        }
+    }
+
+    if (!parsed.useSharp && hasTargetDimensions) {
+        throw new Error('Resizing requires Sharp. Remove --no-sharp to use --width/--height.');
+    }
+
+    if (!parsed.aspectRatioWasProvided && !hasTargetDimensions) {
+        parsed.aspectRatio = '1:1';
+    }
+
+    for (const ref of parsed.references) {
+        if (!ref.imagePath) {
+            throw new Error('Reference path cannot be empty.');
+        }
+    }
+
+    parsed.prompt = parsed.promptParts.join(' ').trim();
+    return parsed;
+}
+
+function resolveOutput(outputArg, format) {
+    const extension = path.extname(outputArg).replace(/^\./, '').toLowerCase();
+    const isFilePath = extension && IMAGE_EXTENSIONS.has(extension);
+
+    if (isFilePath) {
+        const absolute = path.resolve(process.cwd(), outputArg);
+        return {
+            directory: path.dirname(absolute),
+            filename: path.basename(absolute, path.extname(absolute)),
+            extension
+        };
+    }
+
+    return {
+        directory: path.resolve(process.cwd(), outputArg),
+        filename: null,
+        extension: format
+    };
+}
+
+async function ensureApiKey() {
+    const config = loadConfig();
+    const envApiKey = process.env.GEMINI_API_KEY;
+    if (envApiKey && envApiKey.trim()) {
+        return envApiKey.trim();
+    }
+    if (config.apiKey && config.apiKey.trim()) {
+        return config.apiKey.trim();
+    }
+
+    info('No API key found. Let us configure it now.');
+    const newApiKey = await promptApiKey();
+    saveConfig({ ...config, apiKey: newApiKey });
+    success(`API key saved to ${CONFIG_PATH}`);
+    return newApiKey;
+}
+
+async function runConfigCommand() {
+    const existing = loadConfig();
+    if (existing.apiKey) {
+        info(`Existing API key found in ${CONFIG_PATH}.`);
+    } else {
+        info('No saved API key found.');
+    }
+
+    const newApiKey = await promptApiKey();
+    saveConfig({ ...existing, apiKey: newApiKey });
+    success(`API key saved to ${CONFIG_PATH}`);
+}
+
+async function runGeneration(args) {
+    const apiKey = await ensureApiKey();
+    const generator = new GeminiGenerator({ apiKey });
+
+    if (args.model === 'pro') {
+        generator.pro();
+    } else {
+        generator.flash();
+    }
+
+    for (const ref of args.references) {
+        generator.addReference(ref.imagePath, ref.description);
+    }
+
+    info('Generating image(s)...');
+    const generation = await generator.generate(args.prompt, {
+        numberOfImages: args.numberOfImages,
+        quality: args.quality,
+        aspectRatio: args.aspectRatio,
+        width: args.targetWidth,
+        height: args.targetHeight
+    });
+
+    if (generation.text) {
+        info(`Model response: ${generation.text}`);
+    }
+
+    if (!generation.images || generation.images.length === 0) {
+        info('No images were returned by the model.');
+        return;
+    }
+
+    const saveOptions = resolveOutput(args.output, args.format);
+    saveOptions.useSharp = args.useSharp;
+    if (args.targetWidth && args.targetHeight) {
+        info(`Resizing final output to ${args.targetWidth}x${args.targetHeight}.`);
+    }
+    const savedPaths = await generator.save(saveOptions);
+    savedPaths.forEach((savedPath) => {
+        success(`Saved: ${savedPath}`);
+    });
+}
+
+async function main() {
+    try {
+        const args = parseArgs(process.argv.slice(2));
+
+        if (args.showHelp) {
+            printHelp();
+            return;
+        }
+
+        if (args.runConfig) {
+            await runConfigCommand();
+            return;
+        }
+
+        await runGeneration(args);
+    } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+    }
+}
+
+if (require.main === module) {
+    main();
+}
+
+module.exports = {
+    parseArgs,
+    resolveOutput
+};

package/demo/example-multiple.js

@@ -1,15 +1,14 @@
-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();
 
-        // === Multiple variations of the same 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('🎨 Generating multiple variations...\n');
 
@@ -23,7 +22,7 @@ async function main() {
             );
 
             if (result.images && result.images.length > 0) {
-                const saved = await generator.save({ directory: __dirname });
+                const saved = await generator.save({ directory: import.meta.dirname });
                 console.log(`✅ ${saved.length} variations saved:`);
                 saved.forEach(p => console.log(`   - ${p}`));
                 console.log();
@@ -46,4 +45,3 @@ async function main() {
 }
 
 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,21 +22,17 @@ 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));
-                
-                // Get reference metadata to match format
+
                 const refMetadata = generator.getReferenceMetadata();
                 console.log('📊 Reference format:', refMetadata);
-                
-                // Save with same format as reference
-                const saved = await generator.save({ 
+
+                const saved = await generator.save({
                     directory: ptDir,
                     filename: originalName,
                     formatOptions: refMetadata
@@ -64,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/docs/decisions/genmix-cli-output-path-and-reference-text.md

@@ -0,0 +1,12 @@
+---
+id: ydgrqwuq05
+type: decision
+title: 'Decision: GenMix CLI output and refs'
+created: '2026-03-19 12:44:27'
+---
+# Decision: GenMix CLI output path and reference text
+
+**What**: The CLI supports `--output` as either a directory or a full output file path, and supports `--ref` values as `path` or `path:description`.
+**Where**: `cli.js` argument parsing and output resolution.
+**Why**: Users need deterministic output naming/location and richer reference guidance for prompt conditioning.
+**Alternatives rejected**: Separate flags for `--ref-path` + `--ref-text` were rejected because repeated `--ref` with `path:description` is simpler for command-line ergonomics.

package/docs/decisions/genmix-cli-smart-target-size.md

@@ -0,0 +1,12 @@
+---
+id: af6zbnxehw
+type: decision
+title: 'Decision: Smart CLI target size flow'
+created: '2026-03-19 13:28:11'
+---
+# Decision: Smart CLI target size flow
+
+**What**: Added `--size WxH` and `--width/--height` to derive generation aspect ratio automatically and then resize final output to exact dimensions.
+**Where**: `cli.js` and CLI docs in `README.md`.
+**Why**: Users need exact output dimensions (e.g. 400x400) while keeping generation quality independent (e.g. 4K).
+**Alternatives rejected**: Keeping resize manual in code-only API was rejected because CLI users need first-class support.

package/docs/patterns/genmix-cli-avoid-redundant-flags.md

@@ -0,0 +1,12 @@
+---
+id: dw7miivs7w
+type: pattern
+title: 'Lesson: Keep CLI surface minimal'
+created: '2026-03-19 13:34:50'
+---
+# Pattern: Keep CLI surface minimal
+
+**What**: Prefer one clear way to express output dimensions in CLI. Removed redundant `--size` in favor of `--width` + `--height`.
+**Where used**: `cli.js` argument parsing/help and `README.md` CLI documentation.
+**When to apply**: When multiple flags encode the same behavior and one can be removed without losing capability.
+**Why**: Simpler UX, less ambiguity, fewer parsing edge cases.

package/docs/patterns/genmix-single-source-validation.md

@@ -0,0 +1,12 @@
+---
+id: ly0zl6yegp
+type: pattern
+title: 'Lesson: Avoid CLI-core validation duplication'
+created: '2026-03-19 13:36:41'
+---
+# Pattern: Single-source validation in core
+
+**What**: Keep dimension/aspect-ratio derivation and validation in `GeminiGenerator` (core), not duplicated in `cli.js`.
+**Where used**: `cli.js` now only parses input and basic presence/type checks; `_normalizeGenerateOptions()` in `GeminiGenerator` handles semantic validation.
+**When to apply**: Any feature shared by CLI and library/API usage.
+**Why**: Prevent drift, inconsistent behavior, and double-maintenance bugs.

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/GeminiGenerator.js

@@ -4,10 +4,15 @@ const fs = require('fs');
 const path = require('path');
 
 class GeminiGenerator extends BaseGenerator {
+    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]
+     * @param {string} [config.modelId] - Model ID or use GeminiGenerator.MODELS constants
      */
     constructor(config = {}) {
         super(config);
@@ -16,36 +21,124 @@ class GeminiGenerator extends BaseGenerator {
         if (!this.apiKey) {
             throw new Error('API Key is required. Provide it in the constructor or set GEMINI_API_KEY environment variable.');
         }
-        // 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.modelId = config.modelId || GeminiGenerator.MODELS.FLASH;
         this.apiUrl = `https://generativelanguage.googleapis.com/v1beta/models/${this.modelId}:streamGenerateContent`;
         this.referenceMetadata = null;
+        this.references = [];
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * 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;
+    }
+
+    _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]
-     * @param {string|Buffer} [options.referenceImage] - Path to image file, base64 data URI, or Buffer
+     * @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.
+     * @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()
@@ -53,9 +146,14 @@ 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 = [];
+
         return result;
     }
 
@@ -225,27 +323,42 @@ class GeminiGenerator extends BaseGenerator {
         }
     }
 
-    async _generateSingleRequest(prompt, options) {
-        const url = `${this.apiUrl}?key=${this.apiKey}`;
-
-        // Build the parts array
+    /**
+     * 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 = [];
 
-        // Add reference image if provided
-        if (options.referenceImage) {
-            const imageData = await this._processReferenceImage(options.referenceImage);
+        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}` });
+            }
+        }
+
+        parts.push({ text: prompt });
+        return parts;
+    }
+
+    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);
         }
 
-        // Add text prompt
-        parts.push({
-            text: prompt,
-        });
+        const parts = await this._buildReferenceParts(prompt);
 
         // Simplified data structure to minimize conflicts
         const data = {

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.4",
+  "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.",
   "license": "MIT",
   "author": "Martin Clasen",
@@ -8,6 +8,7 @@
     "nano",
     "banana",
     "pro",
+    "flash",
     "image-generator",
     "google-gemini",
     "gemini-api",
@@ -16,15 +17,19 @@
     "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"
   },
   "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.