Skip to navigation
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.

Note: 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. Generate/edit requests also need an auth token issued by your backend, since Signed AI image generation is on by default. See issuing tokens.

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.34.0 as a peer dependency: it relies on uploaderApi.replaceFile. Make that ≥ 1.35.1, since Signed AI image generation is on by default and that is the version whose auth token the editor inherits inside the uploader. 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');
// Your backend endpoint that issues an Uploadcare auth token.
editor.authToken = async () => {
  const response = await fetch('/uploadcare-token');
  if (!response.ok) throw new Error(`token endpoint: ${response.status}`);
  return (await response.json()).token;
};
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));

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:

<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