Image Generation

The unified image API supports current OpenAI GPT Image, Google Gemini native-image, and xAI Grok Imagine generation and editing. The high-level helper defaults to gpt-image-2.5-sunburst, gemini-nano-banana-2.1, or grok-imagine-image-2.0 according to the connector vendor.

Basic Usage

typescript

import { Connector, ImageGeneration, Vendor } from 'oneringai';
import * as fs from 'fs/promises';

// Setup connector
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// Create image generator
const imageGen = ImageGeneration.create({ connector: 'openai' });

// Generate an image
const result = await imageGen.generate({
  prompt: 'A futuristic city at sunset with flying cars',
  model: 'gpt-image-2.5-sunburst', // optional: current vendor default
  size: '1024x1024',
  quality: 'high',
  vendorOptions: { output_format: 'png' },
});

// Save to file
const buffer = Buffer.from(result.data[0].b64_json!, 'base64');
await fs.writeFile('./output.png', buffer);

OpenAI GPT Image

typescript

// GPT Image 2.5 Sunburst is the current default for generation and editing.
const result = await imageGen.generate({
  prompt: 'A serene mountain landscape',
  model: 'gpt-image-2.5-sunburst',
  size: '1536x1024',
  quality: 'high',         // auto, low, medium, high
  vendorOptions: {
    output_format: 'webp',
    background: 'opaque',
  },
});

// The high-level edit API also selects GPT Image 2.5 Sunburst when model is omitted.
const edited = await imageGen.edit({
  image: './source.png',
  prompt: 'Keep the composition and change the weather to snowfall',
  vendorOptions: { input_fidelity: 'high' },
});

OpenAI retired dall-e-2 and dall-e-3 on 2026-05-12. They remain in the registry for historical lookup, but generation/editing requests with these models now reject locally with ProviderError (status 410).

The variations endpoint supported only DALL-E 2 and has no direct replacement. createVariation() remains available for source compatibility and rejects locally before reading the image or making a request. To produce a variation, use edit() with a GPT Image model and an explicit prompt, for example:

typescript

const variation = await imageGen.edit({
  image: './source.png',
  prompt: 'Create a variation of this image with warmer lighting',
});

This is a prompt-based edit, so review its output for your use case. See OpenAI's retirement notice.

Google Gemini native image

typescript

// Setup Google connector
Connector.create({
  name: 'google',
  vendor: Vendor.Google,
  auth: { type: 'api_key', apiKey: process.env.GOOGLE_API_KEY! },
});

const googleGen = ImageGeneration.create({ connector: 'google' });

// Nano Banana 2.1: current general-purpose native image model.
const result = await googleGen.generate({
  prompt: 'A beautiful butterfly in a garden',
  model: 'gemini-nano-banana-2.1',
  size: '2048x2048',
  aspectRatio: '16:9',
  n: 2,
});

// Nano Banana 2 Lite: low-latency 1K generation and editing.
const fastResult = await googleGen.generate({
  prompt: 'A simple geometric pattern',
  model: 'gemini-3.1-flash-lite-image',
});

// Nano Banana Pro: complex layouts and professional 4K output.
const proResult = await googleGen.generate({
  prompt: 'A photorealistic portrait',
  model: 'gemini-3-pro-image',
  vendorOptions: { imageSize: '4096px' },
});

Normalized square sizes map to Gemini's native values: 512x512 → 512, 1024x1024 → 1K, 2048x2048 → 2K, and 4096x4096 → 4K; auto leaves resolution selection to Google. Current native image models reject candidateCount > 1, so OneRingAI implements n (up to the registry limit of four) as bounded parallel generateContent requests. Image edits infer PNG, JPEG, WebP, or GIF MIME types from the source path or bytes.

xAI Grok Imagine

typescript

Connector.create({
  name: 'xai',
  vendor: Vendor.Grok,
  auth: { type: 'api_key', apiKey: process.env.XAI_API_KEY! },
});

const grokImages = ImageGeneration.create({ connector: 'xai' });
const result = await grokImages.generate({
  prompt: 'Editorial product photograph on a cobalt background',
  model: 'grok-imagine-image-2.0',
  aspectRatio: '4:3',
  vendorOptions: {
    resolution: '2K',
    quality: 'medium',
    storage_options: { public: true },
  },
});
// Responses may include b64_json/url plus xAI file_id/public_url metadata.

Current Image Models

The table summarizes the checked-in image registry, not a live account probe. Use getActiveImageModels() and getDeprecatedImageModels() rather than hard-coding this table in a model picker.

Vendor	Model	Lifecycle	Main use	Pricing representation
OpenAI	`gpt-image-2.5-sunburst`	Active, preferred	Highest-quality generation/editing, transparent output	Text/image input and image-output tokens
OpenAI	`gpt-image-2.5-flare`	Active, preferred	Faster generation/editing	Text/image input and image-output tokens
Google	`gemini-nano-banana-2.1`	Active, preferred	General generation/editing up to 4K	$0.067-$0.151 by resolution
Google	`gemini-3.1-flash-lite-image`	Active, preferred	Low-latency 1K work	$0.0336/image
Google	`gemini-3-pro-image`	Active	Professional design and 4K	$0.134-$0.24/image
xAI	`grok-imagine-image-2.0`	Active, preferred	Current generation/editing with quality tiers	$0.04-$0.08; $0.01/input image
xAI	`grok-imagine-image-quality`	Active	Previous higher-fidelity generation/editing	$0.05 at 1K, $0.07 at 2K; $0.01/input image
xAI	`grok-imagine-image`	Active	Fast generation/editing	$0.02/image

Use getActiveImageModels() for callable entries and getDeprecatedImageModels() for still-callable models with a migration notice. Retired records remain queryable but are excluded from the active helper.

Model Introspection

typescript

// List available models
const models = await imageGen.listModels();
console.log('Available models:', models);

// Get model information
const info = imageGen.getModelInfo('gpt-image-2.5-sunburst');
console.log('Max images:', info.capabilities.maxImagesPerRequest);
console.log('Supported sizes:', info.capabilities.sizes);
console.log('Lifecycle:', info.lifecycle);
console.log('Official docs:', info.sources?.documentation);

Cost Estimation

typescript

import { calculateImageCost } from 'oneringai';

// GPT Image 2.5 Sunburst uses actual modality-token usage.
const openaiCost = calculateImageCost('gpt-image-2.5-sunburst', 1, {
  textInputTokens: 100_000,
  cachedImageInputTokens: 200_000,
  imageOutputTokens: 300_000,
});
console.log(openaiCost); // 9.9

// Resolution and input-image accounting for current models.
const googleCost = calculateImageCost('gemini-nano-banana-2.1', 2, {
  resolution: '2048px',
  textInputTokens: 1_000,
});
console.log(googleCost); // 0.2025 (two images plus known text-input usage)

const xaiCost = calculateImageCost('grok-imagine-image-2.0', 2, {
  resolution: '2K-medium',
  inputImages: 1,
});
console.log(xaiCost); // 0.15

Token fields are composable. Supplying only text or image-input token usage adds that known cost to the registry's per-image output estimate; per-image output pricing is replaced only when imageOutputTokens is supplied.