genmix 1.2.5 → 1.2.7

package/README.md

@@ -1,6 +1,6 @@
 # 🎨 GenMix
 
-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).
+AI-powered image generator supporting Google Gemini, Fal Nano Banana 2, and OpenAI GPT Image 2.5. Supports image generation from text prompts and image modification with reference images (Gemini).
 
 ## Features ✨
 
@@ -35,6 +35,41 @@ 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`.
 
+## OpenAI GPT Image 2.5
+
+Set `OPENAI_API_KEY` in your environment (the CLI does not persist OpenAI keys).
+
+```javascript
+const { OpenAIGenerator, OPENAI_MODELS } = require('genmix');
+const generator = new OpenAIGenerator(); // Sunburst by default
+await generator.generate('A watercolor city', { quality: 'high' });
+await generator.save({ filename: 'city', extension: 'png' });
+
+await generator.flare().addReference('./city.png', 'Preserve the buildings')
+  .generate('Change the scene to winter', { quality: 'xhigh' });
+await generator.save({ filename: 'winter', extension: 'png' });
+```
+
+`OPENAI_MODELS.SUNBURST` and `OPENAI_MODELS.FLARE` can also be passed as
+`modelId` in the constructor. Use `.sunburst()` or `.flare()` to switch models.
+References accept local paths, URLs, image data URIs, or Buffers (PNG/JPEG/WebP).
+Successful generation clears queued references; failed requests retain them.
+
+```bash
+genmix "A watercolor city" --provider openai -m sunburst -q high -o city.png
+genmix "Change to winter" --provider openai -m flare --ref city.png -o winter.png
+```
+
+OpenAI quality values are `low`, `medium`, `high`, `xhigh`, `max`, and `auto`
+(default). `numberOfImages` accepts 1–10. `aspectRatio` accepts ratios from 1:3
+to 3:1; generation dimensions approximate that ratio on a 16-pixel grid around
+one megapixel. With no ratio or dimensions, the API chooses the size.
+`width` and `height` set the final dimensions when saving with Sharp, and guide
+the generated aspect ratio. Images are returned as PNG data URIs with the raw API
+response (including usage) in `raw`. Generation and editing use the Image API.
+
+Official documentation: [GPT Image generation](https://developers.openai.com/api/docs/guides/image-generation).
+
 ## Basic Usage
 
 ### The Power of GenMix: Multiple References & Chainable API

package/cli.js

@@ -6,6 +6,7 @@ const os = require('os');
 const readline = require('readline');
 const GeminiGenerator = require('./generators/GeminiGenerator');
 const FalGenerator = require('./generators/FalGenerator');
+const OpenAIGenerator = require('./generators/OpenAIGenerator');
 
 const CONFIG_DIR = path.join(os.homedir(), '.genmix');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
@@ -89,13 +90,14 @@ Usage:
   genmix --help
 
 Options:
-  -p, --provider <gemini|fal> Provider (default: gemini)
+  -p, --provider <gemini|fal|openai> 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 for gemini, auto for fal)
+  -q, --quality <quality> Image quality (Gemini/Fal default: 1K; OpenAI: low|medium|high|xhigh|max|auto)
+  -r, --ratio <ratio>     Aspect ratio (default: 1:1 for gemini, auto for fal/openai)
   --width <px>            Final output width in pixels (requires --height)
   --height <px>           Final output height in pixels (requires --width)
   -m, --model <...>       Model by provider:
+                          openai -> sunburst|flare (default: sunburst)
                           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
@@ -147,7 +149,7 @@ function parseArgs(argv) {
         references: [],
         provider: 'gemini',
         numberOfImages: 1,
-        quality: '1K',
+        quality: null,
         aspectRatio: null,
         aspectRatioWasProvided: false,
         model: null,
@@ -267,14 +269,19 @@ function parseArgs(argv) {
         throw new Error('Number of images must be a positive integer.');
     }
 
-    const quality = parsed.quality.toUpperCase();
-    if (!['1K', '2K', '4K'].includes(quality)) {
+    const quality = (parsed.quality || (parsed.provider === 'openai' ? 'auto' : '1K')).toUpperCase();
+    if (parsed.provider !== 'openai' && !['1K', '2K', '4K'].includes(quality)) {
         throw new Error('Quality must be one of: 1K, 2K, 4K.');
     }
-    parsed.quality = quality;
+    parsed.quality = parsed.provider === 'openai' ? quality.toLowerCase() : quality;
 
-    if (!['gemini', 'fal'].includes(parsed.provider)) {
-        throw new Error('Provider must be "gemini" or "fal".');
+    if (!['gemini', 'fal', 'openai'].includes(parsed.provider)) {
+        throw new Error('Provider must be "gemini", "fal", or "openai".');
+    }
+
+    if (parsed.provider === 'openai') {
+        if (!parsed.modelWasProvided) parsed.model = 'sunburst';
+        if (!['sunburst', 'flare'].includes(parsed.model)) throw new Error('OpenAI model must be sunburst or flare.');
     }
 
     if (parsed.provider === 'gemini' && !parsed.modelWasProvided) {
@@ -313,7 +320,7 @@ function parseArgs(argv) {
     }
 
     if (!parsed.aspectRatioWasProvided && !hasTargetDimensions) {
-        parsed.aspectRatio = parsed.provider === 'fal' ? 'auto' : '1:1';
+        parsed.aspectRatio = parsed.provider !== 'gemini' ? 'auto' : '1:1';
     }
 
     for (const ref of parsed.references) {
@@ -349,6 +356,12 @@ function resolveOutput(outputArg, format) {
 async function ensureApiKey(provider = 'gemini') {
     const config = loadConfig();
 
+    if (provider === 'openai') {
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey || !apiKey.trim()) throw new Error('Set OPENAI_API_KEY to use the OpenAI provider.');
+        return apiKey.trim();
+    }
+
     if (provider === 'fal') {
         const envApiKey = process.env.FAL_API_KEY;
         if (envApiKey && envApiKey.trim()) {
@@ -384,6 +397,10 @@ async function ensureApiKey(provider = 'gemini') {
 }
 
 async function runConfigCommand(provider) {
+    if (provider === 'openai') {
+        info('Set OPENAI_API_KEY in your environment to configure OpenAI.');
+        return;
+    }
     const existing = loadConfig();
     if (provider === 'fal') {
         if (existing.falApiKey) {
@@ -413,9 +430,13 @@ async function runGeneration(args) {
     const apiKey = await ensureApiKey(args.provider);
     const generator = args.provider === 'fal'
         ? new FalGenerator({ apiKey })
-        : new GeminiGenerator({ apiKey });
+        : args.provider === 'openai'
+            ? new OpenAIGenerator({ apiKey })
+            : new GeminiGenerator({ apiKey });
 
-    if (args.provider === 'gemini') {
+    if (args.provider === 'openai') {
+        generator[args.model]();
+    } else if (args.provider === 'gemini') {
         if (args.model === 'pro') {
             generator.pro();
         } else {

package/generators/OpenAIGenerator.js

@@ -0,0 +1,127 @@
+const BaseGenerator = require('./BaseGenerator');
+const fs = require('fs/promises');
+const sharp = require('sharp');
+
+class OpenAIGenerator extends BaseGenerator {
+    static MODELS = {
+        SUNBURST: 'gpt-image-2.5-sunburst',
+        FLARE: 'gpt-image-2.5-flare'
+    };
+
+    constructor(config = {}) {
+        super(config);
+        this.apiKey = config.apiKey || process.env.OPENAI_API_KEY;
+        if (!this.apiKey) {
+            throw new Error('API Key is required. Provide it in the constructor or set OPENAI_API_KEY environment variable.');
+        }
+        this.modelId = config.modelId || OpenAIGenerator.MODELS.SUNBURST;
+        this.references = [];
+    }
+
+    sunburst() {
+        this.modelId = OpenAIGenerator.MODELS.SUNBURST;
+        return this;
+    }
+
+    flare() {
+        this.modelId = OpenAIGenerator.MODELS.FLARE;
+        return this;
+    }
+
+    addReference(image, description = '') {
+        this.references.push({ image, description });
+        return this;
+    }
+
+    clearReferences() {
+        this.references = [];
+        return this;
+    }
+
+    async _referenceBlob(image) {
+        let buffer;
+        if (Buffer.isBuffer(image)) {
+            buffer = image;
+        } else if (typeof image === 'string' && /^https?:\/\//i.test(image)) {
+            const response = await fetch(image);
+            if (!response.ok) throw new Error(`Failed to download reference: HTTP ${response.status}`);
+            buffer = Buffer.from(await response.arrayBuffer());
+        } else if (typeof image === 'string' && image.startsWith('data:')) {
+            const match = image.match(/^data:image\/[\w.+-]+;base64,([A-Za-z0-9+/=\s]+)$/);
+            if (!match) throw new Error('Invalid reference image data URI.');
+            buffer = Buffer.from(match[1], 'base64');
+        } else if (typeof image === 'string' && image.trim()) {
+            buffer = await fs.readFile(image);
+        } else {
+            throw new Error('Reference image must be a file path, URL, data URI, or Buffer.');
+        }
+        const { format } = await sharp(buffer).metadata();
+        if (!['png', 'jpeg', 'webp'].includes(format)) {
+            throw new Error('OpenAI references must be PNG, JPEG, or WebP images.');
+        }
+        return new Blob([buffer], { type: `image/${format}` });
+    }
+
+    async generate(prompt, options = {}) {
+        if (typeof prompt !== 'string' || !prompt.trim()) throw new Error('Prompt is required.');
+        const n = options.numberOfImages ?? 1;
+        if (!Number.isInteger(n) || n < 1 || n > 10) throw new Error('options.numberOfImages must be an integer between 1 and 10.');
+        const quality = options.quality ?? 'auto';
+        if (!['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(quality)) {
+            throw new Error('options.quality must be low, medium, high, xhigh, max, or auto.');
+        }
+        const hasWidth = options.width != null;
+        const hasHeight = options.height != null;
+        if (hasWidth !== hasHeight) throw new Error('Both options.width and options.height are required together.');
+        const width = Number(options.width);
+        const height = Number(options.height);
+        if (hasWidth && (!Number.isInteger(width) || width <= 0 || !Number.isInteger(height) || height <= 0)) {
+            throw new Error('options.width and options.height must be positive integers.');
+        }
+        let ratio = hasWidth ? width / height : null;
+        if (options.aspectRatio && options.aspectRatio !== 'auto') {
+            const match = options.aspectRatio.match(/^(\d+):(\d+)$/);
+            if (!match || Number(match[1]) <= 0 || Number(match[2]) <= 0) throw new Error('Invalid aspect ratio.');
+            const requestedRatio = Number(match[1]) / Number(match[2]);
+            if (ratio && Math.abs(ratio - requestedRatio) > 1e-10) throw new Error('Aspect ratio mismatch with options.width/options.height.');
+            ratio = requestedRatio;
+        }
+        if (ratio && (ratio < 1 / 3 || ratio > 3)) throw new Error('OpenAI aspect ratio must be between 1:3 and 3:1.');
+        const size = ratio
+            ? `${Math.round(Math.sqrt(1024 * 1024 * ratio) / 16) * 16}x${Math.round(Math.sqrt(1024 * 1024 / ratio) / 16) * 16}`
+            : 'auto';
+        const references = [...this.references];
+        if (options.referenceImage != null) references.push({ image: options.referenceImage, description: '' });
+        const descriptions = references.flatMap((ref, index) => ref.description ? [`Image ${index + 1}: ${ref.description}`] : []);
+        const payload = { model: this.modelId, prompt: [...descriptions, prompt].join('\n'), n, quality, size, output_format: 'png' };
+        const headers = { Authorization: `Bearer ${this.apiKey}` };
+        let body;
+        if (references.length) {
+            body = new FormData();
+            for (const [key, value] of Object.entries(payload)) body.append(key, String(value));
+            for (const [index, ref] of references.entries()) {
+                const blob = await this._referenceBlob(ref.image);
+                body.append('image[]', blob, `reference-${index}.${blob.type.split('/')[1]}`);
+            }
+        } else {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(payload);
+        }
+        const response = await fetch(`https://api.openai.com/v1/images/${references.length ? 'edits' : 'generations'}`, { method: 'POST', headers, body });
+        if (!response.ok) {
+            let error;
+            try { error = await response.json(); } catch {}
+            throw new Error(`OpenAI API Error: ${error?.error?.message || `HTTP ${response.status}`}`);
+        }
+        const raw = await response.json();
+        if (!Array.isArray(raw.data) || !raw.data.length || raw.data.some(entry => !entry?.b64_json)) {
+            throw new Error('OpenAI API returned no valid image data.');
+        }
+        const result = { images: raw.data.map(entry => `data:image/png;base64,${entry.b64_json}`), text: '', raw };
+        this.lastGeneration = { prompt, ...result, formatOptions: hasWidth ? { width, height } : null };
+        this.clearReferences();
+        return result;
+    }
+}
+
+module.exports = OpenAIGenerator;

package/index.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "genmix",
-  "version": "1.2.5",
-  "description": "AI-powered image generator supporting Google Gemini and Fal Nano Banana 2.",
+  "version": "1.2.7",
+  "description": "AI-powered image generator supporting Google Gemini, Fal Nano Banana 2, and OpenAI GPT Image 2.5.",
   "license": "MIT",
   "author": "Martin Clasen",
   "keywords": [
@@ -21,7 +21,13 @@
     "generative-ai",
     "genmix",
     "cli",
-    "clasen"
+    "clasen",
+    "openai",
+    "openai-api",
+    "gpt-image",
+    "gpt-image-2.5",
+    "sunburst",
+    "flare"
   ],
   "type": "commonjs",
   "main": "index.js",
@@ -33,9 +39,9 @@
   },
   "dependencies": {
     "hash-factory": "^1.1.2",
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.4"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   }
 }

package/skills/genmix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: AI-powered image generator using Google Gemini, Fal, or OpenAI GPT Image 2.5. 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
@@ -49,3 +49,11 @@ Actions: Create a script using GenMix to generate the image with the prompt "A f
 **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.
+
+## OpenAI GPT Image 2.5
+
+Use `OpenAIGenerator` with `OPENAI_API_KEY` for GPT Image 2.5. Sunburst is the
+default; `.flare()` selects Flare and `.sunburst()` switches back. Use the same
+`addReference()`, `generate()`, and `save()` flow. Quality accepts `low`, `medium`,
+`high`, `xhigh`, `max`, or `auto`, not Gemini resolution labels. CLI example:
+`genmix "A watercolor city" --provider openai -m sunburst -q high -o city.png`.

package/test/openai.test.js

@@ -0,0 +1,87 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const sharp = require('sharp');
+const { OpenAIGenerator } = require('..');
+
+test('OpenAI generation, editing, state and saving', async t => {
+    const png = await sharp({ create: { width: 16, height: 16, channels: 3, background: 'red' } }).png().toBuffer();
+    const calls = [];
+    const originalFetch = global.fetch;
+    global.fetch = async (url, request) => {
+        calls.push({ url, ...request });
+        return Response.json({ data: [{ b64_json: png.toString('base64') }] });
+    };
+    t.after(() => { global.fetch = originalFetch; });
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'genmix-test-'));
+    t.after(() => fs.rm(directory, { recursive: true, force: true }));
+    const generator = new OpenAIGenerator({ apiKey: 'test-key' });
+    const result = await generator.generate('draw', { quality: 'max', width: 120, height: 80 });
+    assert.match(calls[0].url, /\/generations$/);
+    assert.equal(JSON.parse(calls[0].body).quality, 'max');
+    assert.equal(result.images.length, 1);
+    const [saved] = await generator.save({ directory, filename: 'result', extension: 'png' });
+    const metadata = await sharp(saved).metadata();
+    assert.equal(metadata.width, 120);
+    assert.equal(metadata.height, 80);
+    await generator.flare().addReference(png, 'Keep the subject').generate('edit', { numberOfImages: 2 });
+    const edit = calls[1];
+    assert.match(edit.url, /\/edits$/);
+    assert.equal(edit.headers['Content-Type'], undefined);
+    assert.equal(edit.body.get('model'), 'gpt-image-2.5-flare');
+    assert.equal(edit.body.get('n'), '2');
+    assert.match(edit.body.get('prompt'), /Image 1: Keep the subject/);
+    assert.deepEqual(Buffer.from(await edit.body.get('image[]').arrayBuffer()), png);
+    assert.equal(generator.references.length, 0);
+    await generator.generate('next');
+    assert.match(calls[2].url, /\/generations$/);
+    await generator.addReference(saved).addReference(result.images[0]).generate('combine');
+    assert.equal(calls[3].body.getAll('image[]').length, 2);
+});
+
+test('invalid options and API failures preserve queued references', async t => {
+    const generator = new OpenAIGenerator({ apiKey: 'test-key' });
+    const originalFetch = global.fetch;
+    let calls = 0;
+    global.fetch = async () => { calls++; return Response.json({ error: { message: 'quota exceeded' } }, { status: 429 }); };
+    t.after(() => { global.fetch = originalFetch; });
+    for (const options of [{ quality: '4K' }, { numberOfImages: 0 }, { width: 10 }, { aspectRatio: '4:1' }, { width: 100, height: 100, aspectRatio: '3:2' }]) {
+        await assert.rejects(generator.generate('draw', options));
+    }
+    assert.equal(calls, 0);
+    await assert.rejects(generator.generate('draw'), /quota exceeded/);
+    const png = await sharp({ create: { width: 16, height: 16, channels: 3, background: 'red' } }).png().toBuffer();
+    generator.addReference(png);
+    await assert.rejects(generator.generate('edit'), /quota exceeded/);
+    assert.equal(generator.references.length, 1);
+    global.fetch = async () => Response.json({ data: [] });
+    await assert.rejects(generator.generate('edit'), /no valid image data/);
+    assert.equal(generator.lastGeneration, null);
+});
+
+test('CLI selects OpenAI models and saves generated output', async t => {
+    const { execFileSync } = require('node:child_process');
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'genmix-cli-'));
+    t.after(() => fs.rm(directory, { recursive: true, force: true }));
+    const png = await sharp({ create: { width: 16, height: 16, channels: 3, background: 'red' } }).png().toBuffer();
+    const preload = path.join(directory, 'mock.cjs');
+    await fs.writeFile(preload, `
+        const assert = require('node:assert/strict');
+        global.fetch = async (url, request) => {
+            assert.equal(url, 'https://api.openai.com/v1/images/generations');
+            const payload = JSON.parse(request.body);
+            assert.equal(payload.model, 'gpt-image-2.5-' + process.env.TEST_MODEL);
+            assert.equal(payload.quality, 'auto');
+            return Response.json({ data: [{ b64_json: '${png.toString('base64')}' }] });
+        };
+    `);
+    for (const model of ['sunburst', 'flare']) {
+        const output = path.join(directory, `${model}.png`);
+        execFileSync(process.execPath, ['--require', preload, path.resolve('cli.js'), 'draw', '--provider', 'openai', ...(model === 'flare' ? ['-m', model] : []), '-o', output], {
+            env: { ...process.env, OPENAI_API_KEY: 'test-key', TEST_MODEL: model }
+        });
+        assert.equal((await sharp(output).metadata()).format, 'png');
+    }
+});