genmix 1.0.4 → 1.0.5

package/README.md

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

package/demo/example-multiple.js

@@ -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/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,20 +21,56 @@ 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;
     }
 
     /**
      * @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.
@@ -56,6 +97,8 @@ class GeminiGenerator extends BaseGenerator {
             raw: result.raw
         };
 
+        this.references = [];
+
         return result;
     }
 
@@ -225,27 +268,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.0.5",
   "description": "AI-powered image generator using Google Gemini API. Supports image generation from text prompts and image modification with reference images.",
   "license": "MIT",
   "author": "Martin Clasen",
@@ -8,6 +8,7 @@
     "nano",
     "banana",
     "pro",
+    "flash",
     "image-generator",
     "google-gemini",
     "gemini-api",
@@ -24,7 +25,7 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "axios": "^1.13.2",
+    "axios": "^1.13.6",
     "hash-factory": "^1.1.2",
     "sharp": "^0.33.5"
   }

package/skills/genmix/SKILL.md

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