> ## 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-1`).
4. `CHATCLI_IMAGE_PROVIDER=responses` (or `openai` + `CHATCLI_IMAGE_API=responses`) → **OpenAI Responses API**, where a chat model like **`gpt-5.5`** generates the image via the `image_generation` tool.
5. `GOOGLEAI_API_KEY`/`GEMINI_API_KEY` → **native Google** (Imagen `:predict` to generate; Gemini image / "Nano Banana" `:generateContent` to edit).
6. `XAI_API_KEY` → **native xAI grok-image / Aurora** (OpenAI shape, omits `size`). **Generate only.**
7. `CHATCLI_IMAGE_PROVIDER=bedrock` → **AWS Bedrock** (Nova Canvas / Titan Image / Stability 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-1`)     |     ✅    |     ✅    | `/images/edits` (multipart)                                      |
| **Self-hosted** (LocalAI…)     |     ✅    |     ✅    | if it exposes `/images/edits`                                    |
| **Google** (Gemini image)      |     ✅    |     ✅    | `:generateContent` with inline image (Imagen reroutes to Gemini) |
| **Bedrock** (Stability / Nova) |     ✅    |     ✅    | Stability `image-to-image` / Nova `IMAGE_VARIATION`              |
| xAI (Aurora/grok)              |     ✅    |     ❌    | 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 Aurora/grok
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-2-image             # 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.5           # set the model
/config image reset                   # clear overrides
```

Catalog (summary): OpenAI Images `gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`; OpenAI Responses `gpt-5.5`, `gpt-5`; Google `imagen-3.0-generate-002` (generate) / `gemini-2.5-flash-image` (edit); xAI `grok-2-image`; Bedrock `amazon.nova-canvas-v1:0`, `stability.stable-image-core-v1:1`, `stability.sd3-5-large-v1:0`.

***

## 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/Titan** use `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)](/features/vision-input) — the model **sees** images you attach
* [Text-to-Speech & Voice](/features/text-to-speech)
* [Chat Gateway](/features/chat-gateway)