Image Generation & Editing (@image)

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:

CHATCLI_IMAGE_PROVIDER=sdwebui → local Stable Diffusion WebUI (/sdapi/v1/txt2img, default http://localhost:7860). Keyless — the preferred path.
CHATCLI_IMAGE_URL → an OpenAI-compatible endpoint (/images/generations). Covers OpenAI, LocalAI and similar.
OPENAI_API_KEY → OpenAI Images API (default gpt-image-1).
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.
GOOGLEAI_API_KEY/GEMINI_API_KEY → native Google (Imagen :predict to generate; Gemini image / “Nano Banana” :generateContent to edit).
XAI_API_KEY → native xAI grok-image / Aurora (OpenAI shape, omits size). Generate only.
CHATCLI_IMAGE_PROVIDER=bedrock → AWS Bedrock (Nova Canvas / Titan Image / Stability via InvokeModel, reusing the chat provider’s credential chain).

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”.

The @image tool

<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):

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:

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

@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.

Image Input (Vision) — the model sees images you attach
Text-to-Speech & Voice
Chat Gateway

Home

Getting Started

Core Concepts

Features

Security

Support

Image Generation & Editing (@image)

Backend selection (local first)

The @image tool

Multi-provider editing (not locked to one)

Inheritance and automatic routing

Models & per-command config

Formats & details

Privacy & cost

​Backend selection (local first)

​The @image tool

​Multi-provider editing (not locked to one)

​Inheritance and automatic routing

​Models & per-command config

​Formats & details

​Privacy & cost

​Related

Backend selection (local first)

The @image tool

Multi-provider editing (not locked to one)

Inheritance and automatic routing

Models & per-command config

Formats & details

Privacy & cost

Related