Getting started

AI image generation and editing for Uploadcare — a framework-agnostic <uc-ai-enhancer> web component, plus an optional plugin that adds an AI Edit action and a Generate image source to the File Uploader.

Want to see it first? Head to the live demo.

Install

npm

npm install @uploadcare/ai-enhancer

pnpm

pnpm add @uploadcare/ai-enhancer

yarn

yarn add @uploadcare/ai-enhancer

bun

bun add @uploadcare/ai-enhancer

You'll also need an Uploadcare public key to enable generate/edit. Grab one from the Uploadcare dashboard — see API keys in the docs.

Three entry points, imported independently so you only pull in what you use:

Import	What it gives you
@uploadcare/ai-enhancer	Registers the <uc-ai-enhancer> element and exports its public types, the provider, and the localization helpers.
@uploadcare/ai-enhancer/plugin	Just the AiEnhancerPlugin for the File Uploader — no eager component registration.
@uploadcare/ai-enhancer/errors	Just AiEnhancerError and its types — side-effect-free, safe to import in server code (no element registration).

Plugin peer dependency

The plugin entry needs @uploadcare/file-uploader ≥ 1.31.2 as a peer dependency (it relies on uploaderApi.replaceFile). The standalone editor has no peer dependency.

The standalone editor

Importing the package registers the element; configure it via attributes/properties and listen for uc:* events.

import '@uploadcare/ai-enhancer'

<uc-ai-enhancer pubkey="YOUR_PUBLIC_KEY"></uc-ai-enhancer>

const editor = document.querySelector('uc-ai-enhancer')

editor.addEventListener('uc:done', (e) => {
  const { url, uuid, file } = e.detail // file: UploadcareFile
  // persist / display the committed result…
})
editor.addEventListener('uc:cancel', () => {/* closed without committing */})
editor.addEventListener('uc:error', (e) => console.warn(e.detail.error.code, e.detail.error)) // see the error handling guide

See the Components API for the full list of attributes, properties, events, and CSS custom properties, and Error handling for what uc:error carries.

Edit an existing image

Set sourceUuid to an Uploadcare uuid to open the editor in edit mode instead of generating from scratch:

editor.sourceUuid = 'c2499162-eb07-4b93-b31e-94a89a47e858'

The editor resolves the image and frames the canvas to its real aspect ratio. If you already hold the file as an UploadcareFile (returned by @uploadcare/upload-client, or the fileInfo of a File Uploader output entry), pass it as sourceFileInfo instead to skip the lookup — use one or the other, not both. The first successful generation also flips a from-scratch session into edit mode, so you can chain edits.

Where to next

• File Uploader plugin — drop it into the uploader.
• Theming · Localization
• Live demo — try the editor and its layout options.