AI Image Editor options | Uploadcare docs

Every configuration option of the <uc-ai-image-editor> element. Options marked property only hold objects or functions, so they can’t be set as HTML attributes; assign them on the element from JavaScript. Everything else works both as an attribute and as a property. In React, each option maps to the prop of the same name; see the React guide.

Events and CSS custom properties are listed in the API reference.

Public key

Attribute: pubkey · Type: string · Default: ''

Uploadcare public key. Required to enable generate/edit. Grab one from the dashboard (see API keys).

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

Source UUID

Attribute: source-uuid · Type: string | null · Default: null

UUID of an image to edit. When set (or sourceFileInfo is), the editor opens straight in edit mode; when absent, it starts in generate mode. Use either sourceUuid or sourceFileInfo, not both. They’re two ways to point at the same source: a UUID the editor looks up, or the already-resolved file.

editor.sourceUuid = 'c2499162-eb07-4b93-b31e-94a89a47e858';

Source file info

Property only · Type: UploadcareFile | undefined

The source image as an UploadcareFile, e.g. the object returned by @uploadcare/upload-client, or the fileInfo of a File Uploader output entry (OutputFileEntry.fileInfo). Hands the editor the file directly instead of having it look it up from a UUID. Use either sourceFileInfo or sourceUuid, not both.

Output filename

Property only · Type: string | OutputFilenameResolver | undefined

Names the generated/edited result. A string is used verbatim; a function receives (originalFilename, counter) and returns the name (see OutputFilenameResolver). When unset, the result keeps the source’s original filename (and falls back to the provider’s default when generating from scratch).

editor.outputFilename = (original, counter) => `ai-${counter}-${original}`;

Metadata

Property only · Type: Metadata | MetadataCallback | null | undefined

Metadata attached to the resulting Uploadcare file, for both generate and edit. Mirrors the File Uploader’s metadata config: either a static bag (Record<string, string>) or a MetadataCallback resolved at generation time against the source file.

editor.metadata = { source: 'ai-image-editor' };

Base URL

Attribute: base-url · Type: string | undefined

Upload API base URL. Defaults to the provider’s default.

CDN cname

Attribute: cdn-cname · Type: string | undefined

Custom CDN CNAME for resolving results.

CDN cname prefixed

Attribute: cdn-cname-prefixed · Type: string | undefined

Base domain for public-key-prefixed CDN URLs.

Auth token

Property: authToken · Type: string | (() => string | Promise<string>) | { getToken, invalidate } | undefined

Attribute: auth-token · Type: string (the plain-token form only)

An auth token, sent with every request the editor makes. Needs AI Image Editor 0.2.6 or later for the provider object this section describes. Required while Signed AI image generation is on, which it is by default (see setup).

Pass a function and the editor calls it when it needs a token, then caches the result and replaces it 30 seconds before it expires. Pass a plain token instead and it is used as given and never refreshed, so it has to outlive the generation it starts. Leave it unset to send requests without a token. A function that returns nothing fails the request with auth_token_failed.

A { getToken, invalidate } object works in place of the function when you keep your own cache. An AuthTokenCache instance is already this shape, so you can pass one straight in. The editor then adds none of its own, regardless of cacheAuthToken, and invalidateAuthToken() forwards to your invalidate().

Warning: A refused token is not replaced on its own. The editor’s requests raise the error and stop, so an expired or spent token is sent again on the next generation until invalidateAuthToken() drops it.

With React this is an ordinary prop, function and all. On the web component, the auth-token attribute carries the plain form only. A function has to be set as a DOM property, and writing the attribute afterwards replaces it.

Inside File Uploader, the editor uses the uploader’s authToken and its cache, so you do not set this yourself.

Cache auth token

Property only · Type: boolean · Default: true

Whether to cache what an authToken function returns.

Set it to false only if something upstream already caches the token, as the File Uploader plugin does. With caching off, your function runs on every request.

Invalidate auth token

Method: invalidateAuthToken() => void

Drops the cached token, so the next request calls authToken for a new one. Does nothing when authToken is a plain token. In React, reach it through apiRef.

The cache is in memory and dies with the page, so a reload or a new tab needs no call. See when to invalidate.

Assigning a different function does not drop the token, so call this when the signed-in user changes.

A token Uploadcare refused as expired or spent is exactly when to call this: the editor keeps using the cached one otherwise.

Note: A token without a readable exp is never refreshed on its own. Call this to replace it.

Secure delivery proxy URL resolver

Property only · Type: SecureDeliveryProxyUrlResolver | undefined

Secure-delivery resolver: signs/proxies the CDN URLs the editor renders. See signed URLs and the SecureDeliveryProxyUrlResolver type.

Aspect ratios

Attribute: aspect-ratios · Type: AspectRatio[] | null · Default: null

Available aspect ratios for the generate flow. When set as an attribute, the string is parsed; falsy/empty input falls back to the popular set.

<uc-ai-image-editor aspect-ratios="16:9 5:4 1:1"></uc-ai-image-editor>

editor.aspectRatios = [[16, 9], [5, 4], [1, 1]];

Locale name

Attribute: locale-name · Type: string · Default: 'en'

Active locale. The editor lazy-loads its built-in strings for this locale (falling back to English) and layers localeDefinitionOverride on top. See Localization.

Locale definition override

Property only · Type: Record<string, Partial<AiImageEditorLocale>> · Default: {}

Locale string overrides, keyed by locale name, in the same shape as the File Uploader’s localeDefinitionOverride. The section matching localeName is layered on top of that locale’s built-in strings.

editor.localeDefinitionOverride = {
  en: { 'ai-image-editor-generate-btn': 'Make it!' },
};

Presets

Property only · Type: AiPresets · Default: {}

Quick-prompt presets (the chips above the prompt), keyed by mode. Each preset is { label, prompt }: clicking a chip fills the prompt with prompt. Modes left out use their built-in set; an empty array hides that mode’s chips.

editor.presets = {
  generate: [{ label: 'Logo', prompt: 'A logo of ' }],
  edit: [],
};

Keyed by AiEditorMode (and partial), so new modes (e.g. outpaint) extend this additively, without breaking existing configs.

Presets only

Attribute: presets-only · Type: boolean · Default: false

Presets-only mode: hides the free-text prompt so only the preset chips remain, and selecting a preset starts the generation immediately (there’s nothing to type, so no separate send step).

<uc-ai-image-editor presets-only></uc-ai-image-editor>

Composer placement

Attribute: composer-placement · Type: 'bottom' | 'top' · Default: 'bottom'

Which edge the composer (prompt input, presets, aspect-ratio picker) sits on. See UI & layout.

Canvas fit

Attribute: canvas-fit · Type: 'available' | 'full' · Default: 'available'

How the canvas sizes relative to the composer. available (default) shrinks the canvas to the space left by the composer, which is docked outside the image. full lets the canvas fill the whole area with the composer floating over it.

Sizing

Attribute: sizing · Type: 'fill' | 'content' · Default: 'fill'

Who owns the editor’s height. fill (default) makes the editor fill the box you give it: size the host element explicitly with CSS. content fixes the width instead and lets the editor derive its own height from the aspect ratio currently on canvas, within any min-height / max-height you set.

<uc-ai-image-editor sizing="content"></uc-ai-image-editor>

uc-ai-image-editor {
  width: 720px;
  min-height: 360px;
  max-height: 85vh;
}

An unsized host in fill mode falls back to a 480px minimum height rather than collapsing; your own CSS on the element always wins over that fallback. The mode is CSS-driven off the reflected attribute, so an unknown value behaves as fill. See UI & layout.

History placement

Attribute: history-placement · Type: 'composer-above' | 'composer-below' | 'canvas-top' | 'canvas-bottom' · Default: 'composer-above'

Where the history strip sits. composer-above / composer-below are relative to the composer; canvas-top / canvas-bottom pin it to the canvas edge.

Attribute: toolbar-placement · Type: 'bottom' | 'top' | 'none' · Default: 'bottom'

Where the toolbar (Cancel / Done) sits, either bottom (the default) or top. Setting it to none removes the toolbar entirely, in which case your app provides the controls; see Bring your own toolbar.