UploadingAI Image Editor

AI Image Editor quickstart

Stable

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 install @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.

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:

ImportWhat it gives you
@uploadcare/ai-image-editorRegisters the <uc-ai-image-editor> element and exports its public types, the provider, and the localization helpers.
@uploadcare/ai-image-editor/pluginJust the AiImageEditorPlugin for the File Uploader, with no eager component registration.
@uploadcare/ai-image-editor/errorsJust AiImageEditorError and its types. Side-effect-free, so it’s safe to import in server code (no element registration).

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.

1import '@uploadcare/ai-image-editor';
1<uc-ai-image-editor pubkey="YOUR_PUBLIC_KEY"></uc-ai-image-editor>
1const editor = document.querySelector('uc-ai-image-editor');
2
3editor.addEventListener('uc:done', (e) => {
4  const { url, uuid, file } = e.detail; // file: UploadcareFile
5  // persist / display the committed result…
6});
7editor.addEventListener('uc:cancel', () => {/* closed without committing */});
8editor.addEventListener('uc:error', (e) => console.warn(e.detail.error.code, e.detail.error));

Options covers every configuration option. The API reference has the full list of attributes, properties, events, and CSS custom properties, and Error handling explains 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:

1editor.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