> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/19.latest/frontend/image-generation-controller.md).

# Image Generation Controller

Generate images from a text prompt in custom backoffice elements (experimental).

{% hint style="warning" %}
Image Generation is experimental. `generate` returns an error result (server 404) unless the `Umbraco:AI:Experimental:ImageGeneration` feature flag is enabled. See [Enabling image generation](/ai-in-umbraco/19.latest/using-the-api/image-generation.md#enabling-image-generation).
{% endhint %}

`UaiImageGenerationController` provides a frontend API for generating images by calling the Management API. It follows the same controller pattern as [UaiChatController](/ai-in-umbraco/19.latest/frontend/chat-controller.md).

## Import

{% code title="Import" %}

```typescript
import {
    UaiImageGenerationController,
    type UaiImageGenerationOptions,
    type UaiImageGenerationResult,
    type UaiGeneratedImage,
    type UaiImageInput,
} from "@umbraco-ai/core";
```

{% endcode %}

## Constructor

{% code title="Constructor" %}

```typescript
new UaiImageGenerationController(host: UmbControllerHost)
```

{% endcode %}

| Parameter | Type                | Description                                            |
| --------- | ------------------- | ------------------------------------------------------ |
| `host`    | `UmbControllerHost` | The controller host (usually `this` in a Lit element). |

## Methods

### generate

Sends a prompt to the Management API and returns the generated image(s).

{% code title="Signature" %}

```typescript
async generate(
    prompt: string,
    options?: UaiImageGenerationOptions
): Promise<{ data?: UaiImageGenerationResult; error?: unknown }>
```

{% endcode %}

| Parameter | Type                        | Description                                      |
| --------- | --------------------------- | ------------------------------------------------ |
| `prompt`  | `string`                    | The text prompt describing the desired image(s). |
| `options` | `UaiImageGenerationOptions` | Optional configuration (see below).              |

## Options

{% code title="UaiImageGenerationOptions" %}

```typescript
interface UaiImageGenerationOptions {
    /** Profile ID (GUID) or alias. If omitted, uses the default image-generation profile. */
    profileIdOrAlias?: string;
    /** Number of images to generate. */
    count?: number;
    /** Image size as "{width}x{height}" (e.g. "1024x1024"). */
    size?: string;
    /** Response format: "url" (URI to the image), "data" (inline base64), or "hosted" (hosted resource identifier). */
    responseFormat?: string;
    /** Original images to edit (maskless edit). */
    originalImages?: UaiImageInput[];
    /** AbortSignal for cancellation. */
    signal?: AbortSignal;
}
```

{% endcode %}

## Result

{% code title="UaiImageGenerationResult" %}

```typescript
interface UaiGeneratedImage {
    data?: string;      // base64, when returned inline
    url?: string;       // URL, when hosted
    mediaType?: string; // e.g. "image/png"
}

interface UaiImageGenerationResult {
    images: UaiGeneratedImage[];
    usage?: {
        inputTokens?: number;
        outputTokens?: number;
        totalTokens?: number;
    };
}
```

{% endcode %}

## Example

{% code title="image-prompt.element.ts" %}

```typescript
import { LitElement, html } from "lit";
import { customElement, state } from "lit/decorators.js";
import { UaiImageGenerationController } from "@umbraco-ai/core";

@customElement("image-prompt")
export class ImagePromptElement extends LitElement {
    #controller = new UaiImageGenerationController(this);

    @state() private _src?: string;
    @state() private _busy = false;

    async #generate() {
        this._busy = true;
        const { data, error } = await this.#controller.generate(
            "A serene mountain landscape at dawn",
            { size: "1024x1024" },
        );
        this._busy = false;

        if (data?.images.length) {
            const img = data.images[0];
            this._src = img.url ?? `data:${img.mediaType};base64,${img.data}`;
        } else {
            console.error("Image generation failed:", error);
        }
    }

    render() {
        return html`
            <button @click=${this.#generate} ?disabled=${this._busy}>
                ${this._busy ? "Generating…" : "Generate"}
            </button>
            ${this._src ? html`<img src=${this._src} alt="Generated" />` : ""}
        `;
    }
}

declare global {
    interface HTMLElementTagNameMap {
        "image-prompt": ImagePromptElement;
    }
}
```

{% endcode %}

## Related

* [Chat Controller](/ai-in-umbraco/19.latest/frontend/chat-controller.md) - Chat completions in the frontend
* [Image Generation API](/ai-in-umbraco/19.latest/using-the-api/image-generation.md) - Backend image-generation service
* [Types](/ai-in-umbraco/19.latest/frontend/types.md) - All frontend type definitions


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/ai-in-umbraco/19.latest/frontend/image-generation-controller.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.