> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# AI Image Editor quickstart

> Install @uploadcare/ai-image-editor, render the standalone editor, and get your first generated or edited image.

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](/docs/file-uploader/).

> **Note**
>
> **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](/docs/ai-image-editor/errors/#derivative-disabled).

## Install

#### npm

```bash
npm install @uploadcare/ai-image-editor
```

#### pnpm

```bash
pnpm add @uploadcare/ai-image-editor
```

#### yarn

```bash
yarn add @uploadcare/ai-image-editor
```

#### bun

```bash
bun add @uploadcare/ai-image-editor
```

You'll also need an Uploadcare **public key** to enable generate/edit. Grab one
from the [Uploadcare dashboard](https://app.uploadcare.com/); see
[API keys](/docs/start/settings/#keys).

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

> **Info**
>
> 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.

```js
import '@uploadcare/ai-image-editor';
```

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

```js
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));
```

[Options](/docs/ai-image-editor/options/) covers every configuration option. The
[API reference](https://uploadcare.github.io/ai-image-editor/api/components?utm_source=uploadcare-docs\&utm_medium=docs\&utm_campaign=ai-image-editor)
has the full list of attributes, properties, events, and CSS custom
properties, and [Error handling](/docs/ai-image-editor/errors/) 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:

```html
<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:

```js
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`](/docs/uploading-files/), 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](/docs/file-uploader/ai-image-editor/): drop it into the uploader.
* [Integrating into your app](/docs/ai-image-editor/integrating/): Vue, Angular, Svelte, CDN, SSR.
* [Theming](/docs/ai-image-editor/theming/) · [Localization](/docs/ai-image-editor/localization/)