> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Generation & Editing (@image)

> Generate and edit images — local/keyless Stable Diffusion (img2img), OpenAI, Google Gemini, AWS Bedrock and more. Same model for create and edit, with automatic routing when a backend can't edit.

The **`@image`** tool generates **and edits** images via the **`llm/imagegen`** package, **local/keyless-first** and **multi-provider**.

***

## Backend selection (local first)

`imagegen.NewFromEnv` picks one, degrading to `null` when nothing is configured:

1. `CHATCLI_IMAGE_PROVIDER=sdwebui` → local **Stable Diffusion WebUI** (`/sdapi/v1/txt2img`, default `http://localhost:7860`). Keyless — the preferred path.
2. `CHATCLI_IMAGE_URL` → an OpenAI-compatible endpoint (`/images/generations`). Covers OpenAI, LocalAI and similar.
3. `OPENAI_API_KEY` → **OpenAI Images API** (default `gpt-image-2`).
4. `CHATCLI_IMAGE_PROVIDER=responses` (or `openai` + `CHATCLI_IMAGE_API=responses`) → **OpenAI Responses API**, where a chat model like **`gpt-5.6-sol`** generates the image via the `image_generation` tool.
5. `GOOGLEAI_API_KEY`/`GEMINI_API_KEY` → **native Google** (Gemini image / "Nano Banana" `:generateContent`, generate **and** edit; default `gemini-3.1-flash-image` — the Imagen `:predict` family was shut down by Google on 2026-08-17).
6. `XAI_API_KEY` → **native xAI Grok Imagine** (OpenAI shape, omits `size`; default `grok-imagine-image-2.0`). **Generate only.**
7. `CHATCLI_IMAGE_PROVIDER=bedrock` → **AWS Bedrock** (Stability / Nova Canvas via `InvokeModel`, reusing the chat provider's credential chain).

`CHATCLI_IMAGE_PROVIDER` pins the backend (`sdwebui|url|openai|responses|google|xai|zai|minimax|bedrock`); `CHATCLI_IMAGE_API` selects `images|responses` on OpenAI; `CHATCLI_IMAGE_MODEL` sets the model.

<Info>
  **The model is inherited by both generation AND editing.** `@image gen` and `@image edit` read the same `CHATCLI_IMAGE_MODEL`/`CHATCLI_IMAGE_PROVIDER` — one `/model-image` serves both. You never configure "one model to create and another to edit".
</Info>

***

## The @image tool

```text theme={"system"}
<tool_call name="@image" args='{"cmd":"gen","args":{"prompt":"a watercolor fox","size":"1024x1024"}}' />
<tool_call name="@image" args='{"cmd":"edit","args":{"image":"/tmp/fox.png","prompt":"make it Pixar 3D, keep the composition"}}' />
<tool_call name="@image" args='{"cmd":"status"}' />
```

| Subcommand | Purpose |
| - | - |
| `gen {prompt, size?, n?, out?}` | generate image(s) and save to file; `out` = file (1 image) or directory (many) |
| `edit {prompt, image, images?, mask?, strength?, size?, n?, out?}` | edit an existing image (image-to-image / img2img) guided by `prompt` |
| `status` | show the effective backend |
| `models` | list the catalog + your OpenAI account models |

`edit` accepts `image` (path), `mask` (optional PNG for inpainting), `strength` (0..1 — how much to change). The result reports the output file path(s).

***

## Multi-provider editing (not locked to one)

Editing is a **per-API** capability — not every generation backend has an edit endpoint. `@image edit` is capability-gated: editing backends get `Edit`; generation-only ones **refuse cleanly** (and route, see below).

| Backend | Generate | **Edit** | How |
| - | :-: | :-: | - |
| **SD WebUI** (`sdwebui`) | ✅ | ✅ | img2img — **keyless/local** |
| **OpenAI** (`gpt-image-2`) | ✅ | ✅ | `/images/edits` (multipart) |
| **Self-hosted** (LocalAI…) | ✅ | ✅ | if it exposes `/images/edits` |
| **Google** (Gemini image) | ✅ | ✅ | `:generateContent` with inline image |
| **Bedrock** (Stability / Nova) | ✅ | ✅ | Stability `image-to-image` / Nova `IMAGE_VARIATION` |
| xAI (Grok Imagine) | ✅ | ❌ | API only generates |
| Z.AI (CogView/GLM) | ✅ | ❌ | API only generates |
| MiniMax (Image-01) | ✅ | ❌ | API only generates |

## Inheritance and automatic routing

Editing **inherits** the active provider/model. Only when the active backend **can't edit** does `@image edit` route to an edit-capable fallback — and **says so explicitly**:

> ℹ️ Image backend `"xai"` can't edit images; routed to `"sdwebui"` for this edit. Set `CHATCLI_IMAGE_EDIT_PROVIDER` to pin a different one.

Fallback order (each credential-gated, never routing to something that can't run):

```text theme={"system"}
CHATCLI_IMAGE_EDIT_PROVIDER (explicit)
  → SD WebUI (if CHATCLI_IMAGE_URL is set, keyless)
  → OpenAI (if OPENAI_API_KEY)
  → Google (if GEMINI_API_KEY)
  → Bedrock (if an AWS region is present)
```

You can pin the editor without changing the generation provider:

```bash theme={"system"}
export CHATCLI_IMAGE_PROVIDER=xai            # generate with Grok Imagine
export CHATCLI_IMAGE_EDIT_PROVIDER=sdwebui   # but edit on local SD WebUI (keyless)
```

If no editor is available, the tool returns a clear error listing the editing backends and how to configure them.

***

## Models & per-command config

```text theme={"system"}
@image models                         # catalog + your OpenAI account models
/model-image grok-imagine-image-2.0   # set the image model (applies to gen and edit)
/config image                         # overview (backend, api, model, url, edit-provider)
/config image provider responses      # switch backend
/config image api responses           # OpenAI: Images vs Responses
/config image model gpt-5.6-sol       # set the model
/config image reset                   # clear overrides
```

Catalog (summary, Aug 2026): OpenAI Images `gpt-image-2` (default; the older `gpt-image-1`/`1.5`/`1-mini` are deprecated and shut down late 2026); OpenAI Responses `gpt-5.6-sol`/`gpt-5.6-terra`/`gpt-5.6-luna`, `gpt-5.5`; Google `gemini-3.1-flash-image` (default), `gemini-3.1-flash-lite-image`, `gemini-3-pro-image` (`gemini-2.5-flash-image` shuts down 2026-10-02; Imagen was shut down 2026-08-17); xAI `grok-imagine-image-2.0` (default), `grok-imagine-image`; Z.AI `glm-image`, `cogview-4-250304`; MiniMax `image-01`; Bedrock `stability.stable-image-core-v1:1` (default), `stability.stable-image-ultra-v1:1`, `stability.sd3-5-large-v1:0`, `amazon.nova-canvas-v1:0` (legacy, EOL 2026-09-30).

***

## Formats & details

* **OpenAI edits** accepts `image/jpeg`, `image/png`, `image/webp` (not `gif`). The multipart part's `Content-Type` is sent correctly from the image bytes.
* **SD WebUI img2img** uses `denoising_strength` (mapped from `strength`); default `0.6` (visible change while preserving structure).
* **Bedrock Stability** uses `mode: image-to-image` + `strength`; **Nova Canvas** (legacy) uses `IMAGE_VARIATION` with `similarityStrength`.

***

## Privacy & cost

* **Local Stable Diffusion WebUI** is keyless and generates **and** edits on your machine — ideal for privacy and zero cost.
* Cloud backends use the **user's own** key.
* Confirm before generating/editing large batches; mention cost when relevant.

***

## Related

* [Image Input (Vision)](/usage/vision-input) — the model **sees** images you attach
* [Text-to-Speech & Voice](/gateway/text-to-speech)
* [Chat Gateway](/gateway/chat-gateway)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.