Image Generation

Generate images from text prompts using OpenAI, Google, and xAI.

Basic Generation

import { image } from '@providerprotocol/ai';
import { openai } from '@providerprotocol/ai/openai';

const dalle = image({
  model: openai('dall-e-3'),
  params: {
    size: '1024x1024',
    quality: 'hd',
  },
});

const result = await dalle.generate('A sunset over mountains, oil painting style');

// Access the generated image
const img = result.images[0];
console.log(img.revisedPrompt); // DALL-E's enhanced prompt

Saving Images

// Save as file
const bytes = result.images[0].image.toBytes();
await Bun.write('sunset.png', bytes);

// Get as base64
const base64 = result.images[0].image.toBase64();

// Get as data URL
const dataUrl = result.images[0].image.toDataURL();

Provider Options

DALL-E (OpenAI)

import { image } from '@providerprotocol/ai';
import { openai } from '@providerprotocol/ai/openai';

const dalle = image({
  model: openai('dall-e-3'),
  params: {
    size: '1024x1024',    // or '1792x1024', '1024x1792'
    quality: 'hd',         // 'standard' or 'hd'
    style: 'vivid',        // 'vivid' or 'natural'
  },
});

const result = await dalle.generate('A serene Japanese garden');

// DALL-E 3 often revises prompts for better results
console.log(result.images[0].revisedPrompt);

Models: dall-e-3 (highest quality, 1 image per request), dall-e-2 (faster, multiple images, supports editing)

Imagen (Google)

import { image } from '@providerprotocol/ai';
import { google } from '@providerprotocol/ai/google';

const imagen = image({
  model: google('imagen-3.0-generate-001'),
  params: {
    numberOfImages: 4,
    aspectRatio: '16:9',
  },
});

const result = await imagen.generate('A serene Japanese garden');

xAI

import { image } from '@providerprotocol/ai';
import { xai } from '@providerprotocol/ai/xai';

const aurora = image({
  model: xai('grok-2-image'),
});

const result = await aurora.generate('A futuristic cityscape');

Multiple Images

Generate multiple images at once (where supported):

const dalle2 = image({
  model: openai('dall-e-2'),
  params: {
    n: 4,               // Generate 4 images
    size: '512x512',
  },
});

const result = await dalle2.generate('A cute robot');

for (const img of result.images) {
  console.log('Generated:', img.image.mimeType);
}

Image Editing

Edit existing images (DALL-E 2):

import { image, Image } from '@providerprotocol/ai';
import { openai } from '@providerprotocol/ai/openai';

const dalle2 = image({
  model: openai('dall-e-2'),
});

const original = await Image.fromPath('./room.png');
const mask = await Image.fromPath('./mask.png'); // Transparent areas get edited

const result = await dalle2.edit({
  image: original,
  mask: mask,
  prompt: 'Add a potted plant in the corner',
});

Image Variations

Generate variations of an existing image:

const original = await Image.fromPath('./artwork.png');

const result = await dalle2.vary({
  image: original,
  n: 4,
});

Result Structure

interface ImageResult {
  images: GeneratedImage[];
  metadata?: Record<string, unknown>;
}

interface GeneratedImage {
  image: Image;           // The generated image
  revisedPrompt?: string; // Enhanced prompt (DALL-E 3)
  metadata?: Record<string, unknown>;
}

Streaming (Where Supported)

Some providers support streaming generation progress:

const stream = dalle.stream('A detailed landscape');

for await (const event of stream) {
  if (event.type === 'image_delta') {
    console.log('Progress:', event.delta.data?.length, 'bytes');
  }
}

const result = await stream.result;

Prompt Engineering

Tips for better results:

// Be specific about style
await dalle.generate(
  'A sunset over mountains, impressionist oil painting, ' +
  'vibrant colors, visible brushstrokes'
);

// Specify composition
await dalle.generate(
  'A robot, centered composition, studio lighting, ' +
  'white background, product photography'
);

// Include technical details
await dalle.generate(
  'Isometric view of a cozy coffee shop interior, ' +
  'soft lighting, warm colors, detailed furniture'
);

Capabilities by Provider

Feature	DALL-E 3	DALL-E 2	Imagen	xAI
Generate	✓	✓	✓	✓
Edit		✓
Variations		✓
Multiple images		✓	✓
HD quality	✓		✓

Size Options

DALL-E 3

1024x1024 (square)
1792x1024 (landscape)
1024x1792 (portrait)

DALL-E 2

256x256
512x512
1024x1024

Imagen

Various aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4

Error Handling

import { UPPError, ErrorCode } from '@providerprotocol/ai';

try {
  const result = await dalle.generate('...');
} catch (error) {
  if (error instanceof UPPError) {
    if (error.code === ErrorCode.ContentFiltered) {
      console.error('Prompt was blocked by content filter');
    } else if (error.code === ErrorCode.InvalidRequest) {
      console.error('Invalid parameters:', error.message);
    }
  }
}

Working with Generated Images

const result = await dalle.generate('A landscape');
const generated = result.images[0];

// Get raw bytes
const bytes = generated.image.toBytes();

// Get base64
const base64 = generated.image.toBase64();

// Get data URL for web display
const dataUrl = generated.image.toDataURL();

// Check dimensions
console.log(generated.image.width, generated.image.height);
console.log(generated.image.mimeType); // 'image/png'

Complete Example

import { image } from '@providerprotocol/ai';
import { openai } from '@providerprotocol/ai/openai';

async function generateProductImage(description: string) {
  const dalle = image({
    model: openai('dall-e-3'),
    params: {
      size: '1024x1024',
      quality: 'hd',
      style: 'natural',
    },
  });

  const result = await dalle.generate(
    `Professional product photography of ${description}, ` +
    'studio lighting, white background, high detail'
  );

  const bytes = result.images[0].image.toBytes();
  const filename = `product-${Date.now()}.png`;
  await Bun.write(filename, bytes);

  return {
    filename,
    revisedPrompt: result.images[0].revisedPrompt,
  };
}

const { filename, revisedPrompt } = await generateProductImage('wireless earbuds');
console.log('Saved to:', filename);
console.log('DALL-E prompt:', revisedPrompt);