genmix 1.0.0

package/README.md

@@ -0,0 +1,246 @@
+# 🎨 GenMix
+
+AI-powered image generator using Google Gemini API. Supports image generation from text prompts and image modification with reference images.
+
+## Features ✨
+
+- 🖼️ **Image generation** from text descriptions
+- 🎨 **Image modification** using reference images
+- 🔄 **Style transfer** - Apply artistic styles to your images
+- 📐 **Quality control** - Generate in 1K, 2K or 4K
+- 🎯 **Multiple formats** - Supports local paths, URLs and Base64
+- 💾 **Auto-save** with unique hash per prompt
+
+## Installation
+
+```bash
+npm install genmix
+```
+
+## Setup
+
+Create a `.env` file in your project root:
+
+```env
+GEMINI_API_KEY=your_api_key_here
+```
+
+## Basic Usage
+
+### Simple Image Generation
+
+```javascript
+const { GeminiGenerator } = require('genmix');
+
+const generator = new GeminiGenerator();
+
+// Generate an image
+const result = await generator.generate(
+  'A futuristic city with flying cars, cyberpunk style',
+  {
+    numberOfImages: 1,
+    quality: '2K',
+    aspectRatio: '16:9'
+  }
+);
+
+// Save images
+const savedPaths = generator.save('./output');
+console.log('Images saved:', savedPaths);
+```
+
+### Image Modification with Reference Images
+
+```javascript
+// Modify an existing image
+const result = await generator.generate(
+  'Transform this image to have sunset lighting with warm orange tones',
+  {
+    referenceImage: './my-image.png',  // Local path
+    quality: '2K',
+    numberOfImages: 1
+  }
+);
+
+const savedPaths = generator.save('./output');
+```
+
+### Using URLs as Reference
+
+```javascript
+const result = await generator.generate(
+  'Convert this photo into a watercolor painting',
+  {
+    referenceImage: 'https://example.com/image.jpg',  // URL
+    quality: '1K'
+  }
+);
+
+generator.save('./output');
+```
+
+## Configuration Options
+
+### Constructor
+
+```javascript
+new GeminiGenerator({
+  apiKey: string,           // Your Google API key (required)
+  modelId: string           // Model to use (optional, default: 'gemini-3-pro-image-preview')
+})
+```
+
+### generate() Method
+
+```javascript
+await generator.generate(prompt, options)
+```
+
+**Parameters:**
+
+| Option                   | Type          | Description                                 | Default |
+| ------------------------ | ------------- | ------------------------------------------- | ------- |
+| `prompt`                 | string        | Description of what you want to generate    | -       |
+| `options.referenceImage` | string/Buffer | Reference image (path, URL, Base64, Buffer) | -       |
+| `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.    | -       |
+
+## Advanced Examples
+
+### Style Transfer
+
+```javascript
+const result = await generator.generate(
+  'Transform this photo into a Van Gogh style painting with visible brush strokes',
+  {
+    referenceImage: './photo.jpg',
+    quality: '4K'
+  }
+);
+```
+
+### Lighting Modification
+
+```javascript
+const result = await generator.generate(
+  'Change the lighting to dramatic studio lighting with strong shadows',
+  {
+    referenceImage: './portrait.png',
+    quality: '2K'
+  }
+);
+```
+
+### Multiple Variations
+
+```javascript
+const result = await generator.generate(
+  'Add dramatic clouds and enhance colors',
+  {
+    referenceImage: './landscape.jpg',
+    numberOfImages: 3,
+    quality: '1K'
+  }
+);
+
+// Generates 3 variations of the same modification
+```
+
+### Using Buffers
+
+```javascript
+const fs = require('fs');
+const imageBuffer = fs.readFileSync('./image.png');
+
+const result = await generator.generate(
+  'Make this image look cinematic',
+  {
+    referenceImage: imageBuffer
+  }
+);
+```
+
+## Reference Image Formats
+
+GenMix accepts reference images in multiple formats:
+
+1. **Local file path**: `'./image.png'`
+2. **URL**: `'https://example.com/image.jpg'`
+3. **Data URI**: `'data:image/png;base64,iVBORw0KG...'`
+4. **Buffer**: `Buffer.from(...)`
+
+Supported image formats: PNG, JPEG, GIF, WEBP
+
+## Error Handling
+
+```javascript
+try {
+  const result = await generator.generate(prompt, options);
+  
+  if (result.images && result.images.length > 0) {
+    const paths = generator.save('./output');
+    console.log('Success!', paths);
+  } else {
+    console.log('No images generated');
+  }
+} catch (error) {
+  console.error('Error:', error.message);
+  
+  // Common errors:
+  // - 'API Key is required'
+  // - 'Failed to read reference image file'
+  // - 'Failed to download reference image from URL'
+  // - 'Gemini API Error: ...'
+}
+```
+
+## Project Structure
+
+```
+genmix/
+└── generators/
+│   ├── BaseGenerator.js      # Base class with utilities
+│   └── GeminiGenerator.js    # Gemini API implementation
+├── demo/
+│   ├── example.js                # Basic examples
+│   └── example-translation.js    # Translate image
+├── index.js                      # Entry point
+└── README.md
+```
+
+## Best Practices
+
+1. **Clear Prompts**: Be specific about what you want
+   ```javascript
+   // ✅ Good
+   'Add dramatic sunset lighting with orange and pink tones in the sky'
+   
+   // ❌ Vague
+   'Make it better'
+   ```
+
+2. **Appropriate Quality**: 
+   - `1K`: Quick tests
+   - `2K`: General use
+   - `4K`: High quality (slower)
+
+3. **Image Size**: Reference images between 512x512 and 2048x2048 work best
+
+4. **Result Caching**: Images are automatically saved with unique hash based on the prompt
+
+## Additional Resources
+
+- [Code Examples](./demo/)
+- [Google Gemini API Documentation](https://ai.google.dev/)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request.
+
+
+

package/demo/.env

@@ -0,0 +1 @@
+GEMINI_API_KEY="AIzaSyDMy_iCPVzMHF3sSrbCYr2K9PO9lHkCPsg"

package/demo/example-translate.js

@@ -0,0 +1,71 @@
+process.loadEnvFile(); // Native Node.js .env loading (Node 20.12+)
+const { GeminiGenerator } = require('../index');
+const path = require('path');
+const fs = require('fs');
+
+async function main() {
+    try {
+        const generator = new GeminiGenerator();
+
+        // === Option 1: Use a local image ===
+        const localImagePath = path.join(__dirname, 'camera_4126.jpg');
+
+        if (fs.existsSync(localImagePath)) {
+            console.log('📸 Processing local image...\n');
+
+            const result1 = await generator.generate(
+                'Translate this image to Portuguese',
+                {
+                    referenceImage: localImagePath,
+                    quality: '2K',
+                    numberOfImages: 1
+                }
+            );
+
+            if (result1.images && result1.images.length > 0) {
+                const saved = generator.save(__dirname);
+                console.log('✅ Modified image saved at:', saved[0], '\n');
+            } else if (result1.text) {
+                console.log('📝 Result:', result1.text, '\n');
+            }
+        }
+
+
+        // === Option 3: Multiple variations of the same image ===
+        if (fs.existsSync(localImagePath)) {
+            console.log('🎨 Generating multiple variations...\n');
+
+            const result3 = await generator.generate(
+                'Add a vintage film look with grain and vignette effect',
+                {
+                    referenceImage: localImagePath,
+                    quality: '1K',
+                    numberOfImages: 3
+                }
+            );
+
+            if (result3.images && result3.images.length > 0) {
+                const saved = generator.save(__dirname);
+                console.log(`✅ ${saved.length} variations saved:`);
+                saved.forEach(p => console.log(`   - ${p}`));
+                console.log();
+            }
+        }
+
+        console.log('🎉 All examples completed successfully!\n');
+
+    } catch (error) {
+        console.error('❌ Error:', error.message);
+
+        if (error.message.includes('API Key')) {
+            console.error('\n💡 Tip: Make sure you have GEMINI_API_KEY in your .env file');
+        }
+
+        if (error.message.includes('reference image')) {
+            console.error('\n💡 Tip: Verify that the image path is correct');
+        }
+    }
+}
+
+main();
+

package/demo/example.js

@@ -0,0 +1,51 @@
+process.loadEnvFile(); // Native Node.js .env loading (Node 20.12+)
+const { GeminiGenerator } = require('../index');
+
+
+async function exampleBasicGeneration() {
+    console.log('\n=== Example 1: Basic Image Generation ===\n');
+
+    const generator = new GeminiGenerator();
+
+    const prompt = 'A futuristic city with flying cars, cyberpunk style';
+
+    console.log('Generating image...');
+    const result = await generator.generate(prompt, {
+        numberOfImages: 2,
+        quality: '1K', // Options: 1K, 2K, 4K
+        aspectRatio: '1:1'
+    });
+
+    console.log('Generation complete!');
+
+    if (result.text) {
+        console.log('Text response:', result.text);
+    }
+
+    if (result.images && result.images.length > 0) {
+        console.log(`Found ${result.images.length} images.`);
+
+        const savedPaths = generator.save(__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);
+        if (error.stack) {
+            console.error(error.stack);
+        }
+    }
+}
+
+main();

package/demo/genmix/generators/BaseGenerator.js

@@ -0,0 +1,58 @@
+const fs = require('fs');
+const path = require('path');
+const hashFactory = require('hash-factory');
+
+class BaseGenerator {
+  constructor(config = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Generates a hash from the text prompt.
+   * @param {string} prompt 
+   * @param {Object} options 
+   * @returns {string}
+   */
+  generateHash(prompt, options = { length: 10 }) {
+    return hashFactory(prompt, options);
+  }
+
+  /**
+   * Saves generated images to the specified directory using hashed filenames.
+   * @param {string[]} images - Array of base64 image strings.
+   * @param {string} directory - Target directory path.
+   * @param {string} prompt - The prompt used for generation (to create hash).
+   * @param {string} [extension='png'] - File extension.
+   * @returns {string[]} Array of saved file paths.
+   */
+  saveImages(images, directory, prompt, extension = 'png') {
+    if (!images || !Array.isArray(images) || images.length === 0) {
+      return [];
+    }
+
+    // Ensure directory exists
+    if (!fs.existsSync(directory)) {
+      fs.mkdirSync(directory, { recursive: true });
+    }
+
+    const savedPaths = [];
+    const hash = this.generateHash(prompt);
+
+    images.forEach((imgData, index) => {
+      const base64Data = imgData.replace(/^data:image\/\w+;base64,/, "");
+      const buffer = Buffer.from(base64Data, 'base64');
+      
+      // Using format: hash_index.ext
+      const fileName = `${hash}_${index + 1}.${extension}`;
+      const outputPath = path.join(directory, fileName);
+      
+      fs.writeFileSync(outputPath, buffer);
+      savedPaths.push(outputPath);
+    });
+
+    return savedPaths;
+  }
+}
+
+module.exports = BaseGenerator;
+

package/generators/BaseGenerator.js

@@ -0,0 +1,63 @@
+const fs = require('fs');
+const path = require('path');
+const hashFactory = require('hash-factory');
+
+class BaseGenerator {
+    constructor(config = {}) {
+        this.config = config;
+        this.lastGeneration = null;
+    }
+
+    /**
+     * Generates a hash from the text prompt.
+     * @param {string} prompt 
+     * @param {Object} options 
+     * @returns {string}
+     */
+    generateHash(prompt, options = { alpha: true, words: true, now: true }) {
+        const hasher = hashFactory(options);
+        return hasher(prompt);
+    }
+
+    /**
+     * Saves generated images to the specified directory using hashed filenames.
+     * @param {string} directory - Target directory path.
+     * @returns {string[]} Array of saved file paths.
+     */
+    save(directory) {
+        const extension = 'png';
+        const targetImages = this.lastGeneration?.images;
+        const targetPrompt = this.lastGeneration?.prompt;
+
+        if (!targetImages || !Array.isArray(targetImages) || targetImages.length === 0) {
+            console.warn('No images to save.');
+            return [];
+        }
+
+        if (!targetPrompt) {
+            console.warn('No prompt available for hash generation.');
+        }
+
+        // Ensure directory exists
+        if (!fs.existsSync(directory)) {
+            fs.mkdirSync(directory, { recursive: true });
+        }
+
+        const savedPaths = [];
+        targetImages.forEach((imgData, index) => {
+            const base64Data = imgData.replace(/^data:image\/\w+;base64,/, "");
+            const buffer = Buffer.from(base64Data, 'base64');
+
+            const hash = this.generateHash(targetPrompt + '_' + index);
+            const fileName = `${hash}.${extension}`;
+            const outputPath = path.join(directory, fileName);
+
+            fs.writeFileSync(outputPath, buffer);
+            savedPaths.push(outputPath);
+        });
+
+        return savedPaths;
+    }
+}
+
+module.exports = BaseGenerator;

package/generators/GeminiGenerator.js

@@ -0,0 +1,264 @@
+const axios = require('axios');
+const BaseGenerator = require('./BaseGenerator');
+const fs = require('fs');
+const path = require('path');
+
+class GeminiGenerator extends BaseGenerator {
+  /**
+   * @param {Object} [config]
+   * @param {string} [config.apiKey]
+   * @param {string} [config.modelId]
+   */
+  constructor(config = {}) {
+    super(config);
+    this.apiKey = config.apiKey || process.env.GEMINI_API_KEY;
+
+    if (!this.apiKey) {
+      throw new Error('API Key is required. Provide it in the constructor or set GEMINI_API_KEY environment variable.');
+    }
+    // Use the specific model for image generation or default to pro-vision if needed
+    // However, for standard image generation via prompt, specific models like 'gemini-1.5-pro' or 'imagen-3.0-generate-001' are often used.
+    // Keeping the user's modelId preference.
+    this.modelId = config.modelId || 'gemini-3-pro-image-preview';
+    // NOTE: For simple generation, we might not need streamGenerateContent unless we want text streaming.
+    // But let's stick to what worked for text, and adjust the body.
+    this.apiUrl = `https://generativelanguage.googleapis.com/v1beta/models/${this.modelId}:streamGenerateContent`;
+  }
+
+  /**
+   * @param {string} prompt
+   * @param {Object} [options]
+   * @param {string|Buffer} [options.referenceImage] - Path to image file, base64 data URI, or Buffer
+   * @param {string} [options.numberOfImages] - Number of images to generate
+   * @param {string} [options.quality] - Image quality: '1K', '2K', '4K'
+   * @param {string} [options.aspectRatio] - Aspect ratio like '1:1', '16:9', etc.
+   * @returns {Promise<{images: string[], text: string, raw: any}>}
+   */
+  async generate(prompt, options = {}) {
+    // If the user asks for multiple images, we might need to make parallel requests
+    // if the API doesn't support candidateCount > 1 for images.
+    // Based on search results, candidateCount > 1 can cause 400 errors.
+    const numberOfImages = options.numberOfImages || 1;
+
+    let result;
+    if (numberOfImages > 1) {
+      result = await this.generateMultiple(prompt, numberOfImages, options);
+    } else {
+      result = await this._generateSingleRequest(prompt, options);
+    }
+
+    // Store result in state for saveImages()
+    this.lastGeneration = {
+        prompt: prompt,
+        images: result.images,
+        text: result.text,
+        raw: result.raw
+    };
+
+    return result;
+  }
+
+  /**
+   * Processes a reference image and returns base64 data and mime type
+   * @param {string|Buffer} imageInput - File path, base64 data URI, or Buffer
+   * @returns {Promise<{data: string, mimeType: string}>}
+   * @private
+   */
+  async _processReferenceImage(imageInput) {
+    let base64Data;
+    let mimeType = 'image/png'; // default
+
+    if (Buffer.isBuffer(imageInput)) {
+      // If it's already a buffer
+      base64Data = imageInput.toString('base64');
+    } else if (typeof imageInput === 'string') {
+      if (imageInput.startsWith('data:image/')) {
+        // It's a data URI
+        const match = imageInput.match(/^data:(image\/[^;]+);base64,(.+)$/);
+        if (match) {
+          mimeType = match[1];
+          base64Data = match[2];
+        } else {
+          throw new Error('Invalid data URI format for reference image');
+        }
+      } else if (imageInput.startsWith('http://') || imageInput.startsWith('https://')) {
+        // It's a URL - download it
+        try {
+          const response = await axios.get(imageInput, { responseType: 'arraybuffer' });
+          base64Data = Buffer.from(response.data).toString('base64');
+          mimeType = response.headers['content-type'] || 'image/png';
+        } catch (error) {
+          throw new Error(`Failed to download reference image from URL: ${error.message}`);
+        }
+      } else {
+        // Assume it's a file path
+        try {
+          const fileBuffer = fs.readFileSync(imageInput);
+          base64Data = fileBuffer.toString('base64');
+          
+          // Determine mime type from extension
+          const ext = path.extname(imageInput).toLowerCase();
+          const mimeTypes = {
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.gif': 'image/gif',
+            '.webp': 'image/webp'
+          };
+          mimeType = mimeTypes[ext] || 'image/png';
+        } catch (error) {
+          throw new Error(`Failed to read reference image file: ${error.message}`);
+        }
+      }
+    } else {
+      throw new Error('Reference image must be a file path, URL, data URI, or Buffer');
+    }
+
+    return { data: base64Data, mimeType };
+  }
+
+  async generateMultiple(prompt, count, options) {
+    const promises = [];
+    for (let i = 0; i < count; i++) {
+      promises.push(this._generateSingleRequest(prompt, options));
+    }
+
+    try {
+      const results = await Promise.all(promises);
+      
+      const merged = {
+        images: [],
+        text: '',
+        raw: results.map(r => r.raw),
+      };
+
+      for (const res of results) {
+        merged.images.push(...res.images);
+        if (res.text && !merged.text.includes(res.text)) {
+             merged.text += res.text + '\n';
+        }
+      }
+      return merged;
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  async _generateSingleRequest(prompt, options) {
+     const url = `${this.apiUrl}?key=${this.apiKey}`;
+
+     // Build the parts array
+     const parts = [];
+     
+     // Add reference image if provided
+     if (options.referenceImage) {
+       const imageData = await this._processReferenceImage(options.referenceImage);
+       parts.push({
+         inlineData: {
+           mimeType: imageData.mimeType,
+           data: imageData.data
+         }
+       });
+     }
+     
+     // Add text prompt
+     parts.push({
+       text: prompt,
+     });
+
+     // Simplified data structure to minimize conflicts
+     const data = {
+      contents: [
+        {
+          role: 'user', // Role is good practice
+          parts: parts,
+        },
+      ],
+      // Only include generationConfig if there are specific options to set
+      generationConfig: {
+         // 'responseModalities' is often implied or specific to the model.
+         // Removing explicit 'responseModalities' might help if the model detects intent from prompt.
+         // But let's keep basic structure.
+         // candidateCount MUST be 1 for many image models per request.
+         candidateCount: 1, 
+      },
+    };
+    
+    // Only add imageConfig if it's actually supported/needed. 
+    // Some models might reject 'imageConfig' inside 'generationConfig' if they expect text.
+    // However, if we are targeting an image model, we need to be careful.
+    // Let's try sending a cleaner request first.
+    
+    // If specific image options are passed, add them carefully
+    if (options.imageSize || options.aspectRatio || options.quality) {
+         // Note: Not all models support 'imageConfig' this way. 
+         // But if the user is using a model that supports it...
+         data.generationConfig.imageConfig = {};
+         
+         // User mentioned quality is 1k, 2k, 4k. Mapping quality or imageSize to this.
+         const size = options.quality || options.imageSize;
+         if (size) {
+             data.generationConfig.imageConfig.image_size = size; // Expects '1K', '2K', '4K'
+         }
+         
+         if (options.aspectRatio) {
+             data.generationConfig.imageConfig.aspect_ratio = options.aspectRatio;
+         }
+    }
+
+    // Remove 'tools' unless explicitly requested or needed for search grounding.
+    // 'googleSearch' tool might conflict with pure image generation intent on some endpoints.
+    // data.tools = ... (removed)
+
+    try {
+      const response = await axios.post(url, data, {
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+
+      return this.processResponse(response.data);
+    } catch (error) {
+      const errorMessage = error.response?.data?.error?.message || error.message;
+      // Log detailed error for debugging
+      if (error.response?.data) {
+          console.error("API Error Details:", JSON.stringify(error.response.data, null, 2));
+      }
+      throw new Error(`Gemini API Error: ${errorMessage}`);
+    }
+  }
+
+  processResponse(data) {
+    // Handle stream response which might be an array of chunks
+    const chunks = Array.isArray(data) ? data : [data];
+    const images = [];
+    let fullText = '';
+
+    for (const chunk of chunks) {
+      if (chunk.candidates) {
+        for (const candidate of chunk.candidates) {
+          if (candidate.content && candidate.content.parts) {
+            for (const part of candidate.content.parts) {
+              if (part.text) {
+                fullText += part.text;
+              }
+              if (part.inlineData && part.inlineData.mimeType.startsWith('image/')) {
+                // Base64 image data
+                images.push(`data:${part.inlineData.mimeType};base64,${part.inlineData.data}`);
+              }
+              // Handle executable code or other parts if necessary
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      images,
+      text: fullText,
+      raw: data,
+    };
+  }
+}
+
+module.exports = GeminiGenerator;

package/index.js

@@ -0,0 +1,6 @@
+const GeminiGenerator = require('./generators/GeminiGenerator');
+
+module.exports = {
+  GeminiGenerator,
+};
+

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "genmix",
+  "version": "1.0.0",
+  "description": "",
+  "license": "ISC",
+  "author": "",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "axios": "^1.13.2",
+    "hash-factory": "^1.1.2"
+  }
+}