UploadingAI Image Editor

AI Image Editor quickstart

Beta

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.

AI Image Editor is in public beta and available on all paid Uploadcare plans. During the beta, generations and edits are subject to a daily limit per account. On a free project, generation and edit requests fail with the derivative_disabled error.

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.

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

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:

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

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

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 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