Getting started

AI image generation and editing for Uploadcare. The package gives you a framework-agnostic <uc-ai-image-editor> 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-image-editor

pnpm

pnpm add @uploadcare/ai-image-editor

yarn

yarn add @uploadcare/ai-image-editor

bun

bun add @uploadcare/ai-image-editor

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

Public beta

AI Image Editor is in public beta and available on all paid Uploadcare plans. On a free project, generation and edit requests fail with the derivative_disabled error.

The package has three entry points, imported independently so you only pull in what you use:

Import	What it gives you
@uploadcare/ai-image-editor	Registers the <uc-ai-image-editor> element and exports its public types, the provider, and the localization helpers.
@uploadcare/ai-image-editor/plugin	Just the AiImageEditorPlugin for the File Uploader, with no eager component registration.
@uploadcare/ai-image-editor/errors	Just AiImageEditorError and its types. Side-effect-free, so it's 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-image-editor'

<uc-ai-image-editor pubkey="YOUR_PUBLIC_KEY"></uc-ai-image-editor>

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

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

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

Edit an existing image

Point the editor at an Uploadcare uuid to open it in edit mode instead of generating from scratch. In markup, use the source-uuid attribute:

<uc-ai-image-editor
  pubkey="YOUR_PUBLIC_KEY"
  source-uuid="c2499162-eb07-4b93-b31e-94a89a47e858"
></uc-ai-image-editor>

Or set the matching sourceUuid property, which is what you want when the uuid only becomes known at runtime:

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 to skip the lookup — that one is a property only, since an attribute can't carry an object. 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.