generateImage()

Overview

The generateImage() function generates images from text prompts using image generation models. It supports generating multiple images, different sizes, and both base64 and URL outputs.

Function signature

export async function generateImage(
    params: GenerateImageParams
): Promise<ImageGenerateResult>

export type GenerateImageParams = ImageGenerateOptions & {
    model: ImageModel;
};

Parameters

ImageModel

required

The image generation model instance to use.

string

required

The text description of the image to generate. Must not be empty.

number

Number of images to generate. Defaults to 1.

string

Image dimensions. Format and available sizes depend on the provider.Common sizes:

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

ImageProviderOptions

Provider-specific options, namespaced by provider name (e.g. { openai: { quality: 'hd' } }).

Return value

Returns a Promise<ImageGenerateResult> with the following properties:

GeneratedImage[]

Array of generated images. Length matches the n parameter.

Show GeneratedImage

string | undefined

Base64-encoded image data (if requested/available).

string | undefined

URL to the generated image (if available).

string | undefined

The actual prompt used by the model after any modifications or safety filtering.

Examples

Basic image generation

import { generateImage } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';

const openai = createOpenAI();

const result = await generateImage({
  model: openai.imageModel('gpt-image-1'),
  prompt: 'A serene landscape with mountains and a lake at sunset'
});

console.log(result.images[0].url);
// Save or display the image URL

Generate multiple images

const result = await generateImage({
  model: openai.imageModel('gpt-image-1'),
  prompt: 'A cute robot playing guitar',
  n: 4 // Generate 4 variations
});

console.log(`Generated ${result.images.length} images`);
result.images.forEach((image, i) => {
  console.log(`Image ${i + 1}: ${image.url}`);
});

Custom size

const result = await generateImage({
  model: openai.imageModel('gpt-image-1'),
  prompt: 'A futuristic city skyline',
  size: '1792x1024' // Wide landscape format
});

console.log('Generated landscape image:', result.images[0].url);

Get base64 image data

const result = await generateImage({
  model: openai.imageModel('gpt-image-1'),
  prompt: 'A detailed illustration of a dragon',
  providerOptions: {
    openai: { responseFormat: 'b64_json' },
  }
});

const base64Data = result.images[0].base64;
if (base64Data) {
  // Save to file
  const fs = await import('fs/promises');
  const buffer = Buffer.from(base64Data, 'base64');
  await fs.writeFile('dragon.png', buffer);
}

Check revised prompt

const result = await generateImage({
  model: openai.imageModel('gpt-image-1'),
  prompt: 'cat'
});

if (result.images[0].revisedPrompt) {
  console.log('Original:', 'cat');
  console.log('Revised:', result.images[0].revisedPrompt);
  // Revised might be: "A fluffy orange tabby cat sitting on a windowsill..."
}

Save image to file

import { writeFile } from 'fs/promises';

const result = await generateImage({
  model: openai.imageModel('gpt-image-1'),
  prompt: 'Abstract art with vibrant colors'
});

const imageUrl = result.images[0].url;
if (imageUrl) {
  // Download and save
  const response = await fetch(imageUrl);
  const buffer = await response.arrayBuffer();
  await writeFile('abstract-art.png', Buffer.from(buffer));
  console.log('Image saved!');
}

Generate with style instructions

const result = await generateImage({
  model: openai.imageModel('gpt-image-1'),
  prompt: 'A portrait of a wise old wizard, oil painting style, ' +
          'detailed brushstrokes, warm lighting, fantasy art'
});

console.log(result.images[0].url);

Error handling

import { ValidationError } from '@core-ai/core-ai';

try {
  const result = await generateImage({
    model: openai.imageModel('gpt-image-1'),
    prompt: '' // Empty prompt
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Image generation failed:', error.message);
    // Output: "prompt must not be empty"
  }
}

Generate portrait and landscape variants

const prompt = 'A magical forest with glowing mushrooms';

const [portrait, landscape, square] = await Promise.all([
  generateImage({
    model: openai.imageModel('gpt-image-1'),
    prompt,
    size: '1024x1792' // Portrait
  }),
  generateImage({
    model: openai.imageModel('gpt-image-1'),
    prompt,
    size: '1792x1024' // Landscape
  }),
  generateImage({
    model: openai.imageModel('gpt-image-1'),
    prompt,
    size: '1024x1024' // Square
  })
]);

console.log('Portrait:', portrait.images[0].url);
console.log('Landscape:', landscape.images[0].url);
console.log('Square:', square.images[0].url);

Model Support

Different providers expose image generation models through imageModel():

import { createOpenAI } from '@core-ai/openai';
const openai = createOpenAI();

const gptImage = openai.imageModel('gpt-image-1');

const result = await generateImage({
  model: gptImage,
  prompt: 'A beautiful sunset'
});

Important notes

Check revisedPrompt when you want to inspect how the provider expanded or filtered your original prompt.

For best results, be specific and descriptive in your prompts. Include details about style, composition, lighting, colors, and mood.

Provider-specific options

OpenAI

const result = await generateImage({
  model: openai.imageModel('gpt-image-1'),
  prompt: 'A cat',
  providerOptions: {
    openai: {
      quality: 'hd',
      style: 'vivid',
      responseFormat: 'url',
    },
  }
});

Common use cases

Content Creation: Generate illustrations for articles and blog posts
Marketing: Create social media graphics and ad visuals
Product Design: Visualize product concepts and variations
Game Development: Generate concept art and textures
Education: Create visual aids and diagrams
Personal Projects: Generate artwork for presentations or creative projects

Best practices

Be Specific: Detailed prompts produce better results
Iterate: Generate multiple variations to find the best result
Use Style Keywords: Include art style, medium, and technique terms
Check Revised Prompts: Inspect provider prompt rewrites when outputs differ from your original request
Handle Errors: Prompts may be rejected for safety reasons

Errors

Throws ValidationError if:

Prompt is empty

May also throw:

ProviderError if the provider returns an error during image generation
Model encounters an error during generation
Prompt violates content policy

import { CoreAIError, ProviderError } from '@core-ai/core-ai';

try {
  const result = await generateImage({
    model: openai.imageModel('gpt-image-1'),
    prompt: 'inappropriate content'
  });
} catch (error) {
  if (error instanceof ProviderError) {
    console.error('Provider error:', error.provider, error.statusCode);
  } else if (error instanceof CoreAIError) {
    console.error('Generation failed:', error.message);
  }
}

​Overview

​Function signature

​Parameters

​Return value

​Examples

​Basic image generation

​Generate multiple images

​Custom size

​Get base64 image data

​Check revised prompt

​Save image to file

​Generate with style instructions

​Error handling

​Generate portrait and landscape variants

​Model Support

​Important notes

​Provider-specific options

​OpenAI

​Common use cases

​Best practices

​Errors

Overview

Function signature

Parameters

Return value

Examples

Basic image generation

Generate multiple images

Custom size

Get base64 image data

Check revised prompt

Save image to file

Generate with style instructions

Error handling

Generate portrait and landscape variants

Model Support

Important notes

Provider-specific options

OpenAI

Common use cases

Best practices

Errors