AI Image Generation

Generate images from text prompts directly in the editor. Users describe what they want, pick a style and aspect ratio, and the result is inserted into their design.

Configuration

ai: {
  mode: 'external',
  features: {
    imageGeneration: true,
  },
  callbacks: {
    onImageGenerate: async (params: AIImageGenerationParams) => {
      // call your image generation API
      return result;
    },
  },
}

AIImageGenerationParams

Property	Type	Description
prompt	string	The user's image description.
style	'photo' | 'illustration' | 'flat' | '3d' | 'painting'	Visual style.
aspectRatio	'1:1' | '16:9' | '9:16' | '4:3' | '3:4'	Output aspect ratio.
count	number	Number of images to generate (1–4).

AIImageGenerationResult

The callback must return a Promise<AIImageGenerationResult>:

interface AIImageGenerationResult {
  images: Array<{
    url: string;      // publicly accessible image URL
    width: number;    // pixel width
    height: number;   // pixel height
  }>;
}

Example Implementation

onImageGenerate: async (params: AIImageGenerationParams): Promise<AIImageGenerationResult> => {
  const response = await fetch('/api/ai/images/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prompt: params.prompt,
      style: params.style,
      aspect_ratio: params.aspectRatio,
      n: params.count,
    }),
  });

  if (!response.ok) {
    throw new Error('Image generation failed');
  }

  const data = await response.json();

  return {
    images: data.images.map((img: any) => ({
      url: img.url,
      width: img.width,
      height: img.height,
    })),
  };
},

info

The editor displays a loading state while the callback resolves. Return URLs that are publicly accessible — the editor renders them directly in <img> tags.

warning

Generated image URLs must support CORS if the user later exports the design as an image or PDF.

User Flow

1. User clicks the AI Image button in the image block toolbar.
2. A dialog prompts for description, style, and aspect ratio.
3. The editor calls onImageGenerate with the parameters.
4. Returned images are shown as a grid for the user to pick from.
5. The selected image is inserted into the design.

Error Handling

Throw an error or return a rejected promise to display a failure toast:

onImageGenerate: async (params) => {
  const res = await fetch('/api/ai/images/generate', {
    method: 'POST',
    body: JSON.stringify(params),
  });
  if (!res.ok) throw new Error('Generation failed');
  return await res.json();
},