PHPackages spacecatninja/ai-image-editor - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Image & Media](/categories/media) 4. / 5. spacecatninja/ai-image-editor ActiveCraft-plugin[Image & Media](/categories/media) spacecatninja/ai-image-editor ============================= Edit images in the Craft CMS control panel using natural language, powered by AI. 1.0.0(today)00proprietaryPHPPHP ^8.2 Since Aug 5Pushed todayCompare [ Source](https://github.com/spacecatninja/craft-ai-image-editor)[ Packagist](https://packagist.org/packages/spacecatninja/ai-image-editor)[ RSS](/packages/spacecatninja-ai-image-editor/feed)WikiDiscussions main Synced today READMEChangelogDependencies (4)Versions (2)Used By (0) AI Image Editor for Craft CMS ============================= [](#ai-image-editor-for-craft-cms) Edit and generate image assets in the Craft CMS control panel using natural language, powered by AI. Open any image asset and tell the editor what you want in plain words — *"make the background white"*, *"remove the coffee cup"*, *"make it look like golden hour"* — then iterate in a chat-style loop until it's right and save the result, either as a new asset or back over the original. Need an image that doesn't exist yet? Describe it and generate one from scratch. No fixed one-click filters, no round-trips to a desktop editor, no leaving Craft. Requirements ------------ [](#requirements) - Craft CMS 5.0+ - PHP 8.2+ - An API key for at least one supported provider — Google Gemini, OpenAI, Black Forest Labs (FLUX), or xAI (Grok). Bring your own key; requests go directly from your server to the provider. Installation ------------ [](#installation) To install the plugin, either install it from the Plugin Store, or follow these instructions: 1. Install with Composer via `composer require spacecatninja/ai-image-editor` from your project directory. 2. Install the plugin in the Craft Control Panel under Settings → Plugins, or from the command line via `php craft plugin/install ai-image-editor`. 3. For the plugin work, you need to [configure at least one driver](#configuration) and verify the connection with `php craft ai-image-editor/test-connection`. But first, read on! Highlights ---------- [](#highlights) - **Natural-language editing, inside the control panel.** Free-form instructions in a chat-style composer — not a fixed set of one-click filters. Editors never leave Craft, and never round-trip through a desktop image editor. - **Generate images from scratch, too.** Beyond editing existing assets, describe an image in words and the plugin creates it as a new asset — straight from an asset index or an asset-selection modal. - **Iterate cheaply, finalize sharp.** Turns run as fast, low-resolution **drafts** while you refine the look; the full-resolution version is rendered only once you accept, with a side-by-side draft/final comparison so nothing changes behind your back. - **Bring your own AI provider.** Four drivers ship in the box — **Gemini**, **OpenAI**, **FLUX**, and **Grok** — chosen in config and switchable per session. Requests go directly from your server to the provider with your own API key, and other plugins can register more drivers. - **Built to stay faithful.** A "Precise edits" mode, multi-turn provider chaining, and automatic aspect-ratio pinning combine to change only what you asked for and stop quality from drifting across successive edits. - **Feels like part of Craft.** Reuses the native image-editor interface and its two save actions — replace the original in place, or save as a new sibling asset — respects your volume permissions, auto-detects focal points, and names generated files from an AI description of what's in them. - **Ready for content-disclosure rules.** An optional field flags every AI-edited or -generated asset so you can meet AI-labeling regulations, and it pairs with [Imager X](https://imager-x.spacecat.ninja/) when you need a watermark burned into the pixels. - **Cloud- and cluster-friendly.** Works unchanged on Craft Cloud and on load-balanced or ephemeral filesystems — working images live in Craft's temporary filesystem, never a hardcoded local path. - **Configured as code.** No settings screen to click through: everything lives in `config/ai-image-editor.php`, so it's versioned and multi-environment by default. - **Extensible.** Before/after events on every edit and save let you observe, adjust, or veto them, and you can register custom drivers for other providers. How it works ------------ [](#how-it-works) - Edits during the chat loop are performed at the configured **working resolution** (default 1K). These are the **draft** versions: cheap and fast, good enough to judge whether an edit is right. - When you accept the result, the last accepted draft is regenerated once at the **final resolution** (default 2K) before it's saved as an asset. (Drivers with a single resolution tier, like OpenAI, skip this and save the draft directly.) - **Note:** the finalize step is a generative regeneration, not a pixel-preserving upscale. The editor shows a draft/final comparison so you can catch drift, and lets you save the draft instead if the final version isn't faithful. - Like the native image editor, there are two save actions: **Save** replaces the original asset's file (the asset and its relations stay intact, requires the "Replace files" volume permission), and **Save as a new asset** creates a sibling asset in the same folder (requires the "Save assets" volume permission). - Intermediate results are never Craft assets. They live in Craft's temporary filesystem and are purged when a session is finalized, discarded, or abandoned (see [Craft Cloud and ephemeral filesystems](#craft-cloud-and-ephemeral-filesystems)). - In both cases the file is named `{original-basename}-edit-{timestamp}.{ext}`. If the original already has an edit suffix, it's replaced rather than stacked, so re-editing doesn't compound it. - As part of saving, the image's focal point is detected and set on the asset before it's created, so transforms anchor to the subject from the first render. Assets that already have a focal point keep it. Disable with `'autoFocalPoint' => false`. - If you set `aiGeneratedField` to the handle of a lightswitch field on your asset volumes, that field is switched on for every asset the plugin edits or generates (including replaced originals), giving you a durable, queryable flag to mark AI-touched images. See [Marking AI-generated content](#marking-ai-generated-content). ### Generating new images [](#generating-new-images) Besides editing existing assets, the plugin can create images from scratch. A **Generate** button appears next to the upload button on asset indexes (for users who can save assets in the volume) and inside asset selection modals. It opens the same editor without a source image: describe what you want, iterate in drafts, and accept to save. Generated assets land in the folder that was selected in the index, named after an AI description of the image (e.g. `golden-retriever-on-a-beach.png`), falling back to the first prompt. Since there is no original, only "Save as a new asset" is offered. ### Reducing content drift [](#reducing-content-drift) Generative editing can change more than you asked for. The plugin does several things to keep edits faithful: - The **"Precise edits" toggle** in the editor (on by default) appends content-preservation instructions to every prompt, telling the model to change only what was requested. Turn it off for deliberately creative edits, or tune the wording with the `preserveInstructions` setting. - On providers that support it (currently Gemini, via interaction chaining), consecutive edits reuse the provider's **multi-turn state** instead of re-uploading the previous result, so quality loss doesn't compound across turns. The stateless drivers (OpenAI, FLUX, Grok) re-send the current working image each turn instead. - The output **aspect ratio is pinned** to the source image's, preventing recomposition. For deliberate ratio changes ("crop this to a square"), pick a ratio in the editor's aspect ratio dropdown instead of relying on the prompt, the default "Match original" follows the current working image. If simple edits still drift, you can change to more advanced models or adjust the fidelity knobs per driver (Gemini's `'thinkingLevel'`, OpenAI's `quality`, FLUX's `safetyTolerance`, to name a few). Drivers ------- [](#drivers) Four drivers ship with the plugin, selected with the `driver` setting: - **`gemini`**: Google's Gemini image models. Model aliases `nano-banana-pro` (gemini-3-pro-image) and `nano-banana-2` (gemini-3.1-flash-image), resolution tiers up to 4K, 10 aspect ratios, and multi-turn interaction chaining for low-drift iteration. - **`openai`**: OpenAI's GPT Image models (`gpt-image-2`, `gpt-image-1.5`, `gpt-image-1-mini`). Output tops out around 1.5K, so a single `1K` tier is exposed and accepting a result saves directly without a regeneration step. Three aspect ratios (1:1, 3:2, 2:3). The "Precise edits" toggle maps to the API's `input_fidelity` parameter in addition to prompt instructions. Turns are stateless (no chaining). - **`flux`**: Black Forest Labs' FLUX.2 models (`flux-2-pro`, `flux-2-flex`), which do both editing and text-to-image generation at up to ~4MP, so `1K` and `2K` tiers are exposed. Stateless turns. The API is asynchronous (the plugin submits, polls, and downloads the result behind the usual spinner). FLUX has **no vision model**, so set `analysisDriver` to `gemini` or `openai` if you want focal point detection and descriptive filenames. - **`grok`**: xAI's Grok Imagine models (`grok-imagine-image`, `grok-imagine-image-quality`), doing both editing and text-to-image generation at `1K` and `2K`. Stateless turns. Grok has its own vision model (`grok-4.5`), so it handles the analysis tasks in-provider, no `analysisDriver` needed. The output format is chosen by the API, so no format tier is offered. The `gemini`, `openai` and `grok` drivers also handle the analysis tasks (focal point detection, descriptive filenames) with their provider's vision models, configurable via each driver's `analysisModel` key. `flux` has no vision model, so it relies on `analysisDriver` (below). Additional drivers can be registered by other plugins through the `EVENT_REGISTER_EDIT_DRIVERS` event (see [Extending](#extending)). They read their own configuration from `driverConfig[handle]`, so a third-party driver gets typed-free settings without touching the core config, and the simplest ones can extend `spacecatninja\aiimageeditor\drivers\BaseEditDriver` to inherit config reading, credentials, prompt building, and the analysis wrappers. Configuration ------------- [](#configuration) There is no control panel settings screen. All configuration is done in `config/ai-image-editor.php`, using Craft's standard multi-environment config format: ```