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

# Geração e Edição de Imagem (@image)

> Gera e edita imagens — Stable Diffusion local/keyless (img2img), OpenAI, Google Gemini, AWS Bedrock e mais. Mesmo modelo para criar e editar, com roteamento automático quando o backend não edita.

O tool **`@image`** gera **e edita** imagens via o pacote **`llm/imagegen`**, **local/keyless-first** e **multi-provedor**.

***

## Seleção de backend (local primeiro)

`imagegen.NewFromEnv` escolhe, degradando para `null` quando nada está configurado:

1. `CHATCLI_IMAGE_PROVIDER=sdwebui` → **Stable Diffusion WebUI** local (`/sdapi/v1/txt2img`, default `http://localhost:7860`). Keyless — o caminho preferido.
2. `CHATCLI_IMAGE_URL` → endpoint OpenAI-compatível (`/images/generations`). Cobre OpenAI, LocalAI e similares.
3. `OPENAI_API_KEY` → **OpenAI Images API** (default `gpt-image-1`).
4. `CHATCLI_IMAGE_PROVIDER=responses` (ou `openai` + `CHATCLI_IMAGE_API=responses`) → **OpenAI Responses API**, onde um modelo de chat como **`gpt-5.5`** gera a imagem via a tool `image_generation`.
5. `GOOGLEAI_API_KEY`/`GEMINI_API_KEY` → **Google nativo** (Imagen `:predict` para gerar; Gemini image / "Nano Banana" `:generateContent` para editar).
6. `XAI_API_KEY` → **xAI grok-image / Aurora nativo** (shape OpenAI, omite `size`). **Só gera.**
7. `CHATCLI_IMAGE_PROVIDER=bedrock` → **AWS Bedrock** (Nova Canvas / Titan Image / Stability via `InvokeModel`, reusando a cadeia de credenciais do provider de chat).

`CHATCLI_IMAGE_PROVIDER` fixa o backend (`sdwebui|url|openai|responses|google|xai|zai|minimax|bedrock`); `CHATCLI_IMAGE_API` escolhe `images|responses` no OpenAI; `CHATCLI_IMAGE_MODEL` ajusta o modelo.

<Info>
  **O modelo é herdado por geração E edição.** `@image gen` e `@image edit` leem o mesmo `CHATCLI_IMAGE_MODEL`/`CHATCLI_IMAGE_PROVIDER` — um único `/model-image` vale para os dois. Você nunca configura "um modelo para criar e outro para editar".
</Info>

***

## Tool @image

```text theme={"system"}
<tool_call name="@image" args='{"cmd":"gen","args":{"prompt":"uma raposa em aquarela","size":"1024x1024"}}' />
<tool_call name="@image" args='{"cmd":"edit","args":{"image":"/tmp/raposa.png","prompt":"deixe em estilo Pixar 3D, mantendo a composição"}}' />
<tool_call name="@image" args='{"cmd":"status"}' />
```

| Subcomando                                                         | Função                                                                               |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `gen {prompt, size?, n?, out?}`                                    | gera imagem(ns) e salva em arquivo; `out` = arquivo (1 imagem) ou diretório (várias) |
| `edit {prompt, image, images?, mask?, strength?, size?, n?, out?}` | edita uma imagem existente (image-to-image / img2img) guiada por `prompt`            |
| `status`                                                           | mostra o backend efetivo                                                             |
| `models`                                                           | lista o catálogo + modelos da sua conta OpenAI                                       |

`edit` aceita `image` (caminho), `mask` (PNG opcional para inpainting), `strength` (0..1 — quanto mudar a imagem). O resultado reporta o(s) caminho(s) do(s) arquivo(s).

***

## Edição multi-provedor (não depende de um só)

Edição é uma capacidade **por-API** — nem todo backend de geração tem endpoint de edição. O `@image edit` é gateado por capability: backends que editam recebem o `Edit`; os que só geram **recusam de forma clara** (e roteiam, veja abaixo).

| Backend                        | Gera | **Edita** | Como                                                               |
| ------------------------------ | :--: | :-------: | ------------------------------------------------------------------ |
| **SD WebUI** (`sdwebui`)       |   ✅  |     ✅     | img2img — **keyless/local**                                        |
| **OpenAI** (`gpt-image-1`)     |   ✅  |     ✅     | `/images/edits` (multipart)                                        |
| **Self-hosted** (LocalAI…)     |   ✅  |     ✅     | se expõe `/images/edits`                                           |
| **Google** (Gemini image)      |   ✅  |     ✅     | `:generateContent` com imagem inline (Imagen reroteia para Gemini) |
| **Bedrock** (Stability / Nova) |   ✅  |     ✅     | Stability `image-to-image` / Nova `IMAGE_VARIATION`                |
| xAI (Aurora/grok)              |   ✅  |     ❌     | a API só gera                                                      |
| Z.AI (CogView/GLM)             |   ✅  |     ❌     | a API só gera                                                      |
| MiniMax (Image-01)             |   ✅  |     ❌     | a API só gera                                                      |

## Herança e roteamento automático

A edição **herda** o provider/modelo ativo. Só quando o backend ativo **não edita** é que o `@image edit` roteia para um fallback edit-capable — e **avisa explicitamente**:

> ℹ️ O backend de imagem `"xai"` não edita imagens; roteado para `"sdwebui"` nesta edição. Defina `CHATCLI_IMAGE_EDIT_PROVIDER` para fixar outro.

Ordem do fallback (cada um gated por credencial, nunca roteia para algo que não roda):

```text theme={"system"}
CHATCLI_IMAGE_EDIT_PROVIDER (explícito)
  → SD WebUI (se CHATCLI_IMAGE_URL setado, keyless)
  → OpenAI (se OPENAI_API_KEY)
  → Google (se GEMINI_API_KEY)
  → Bedrock (se região AWS presente)
```

Você pode fixar o editor sem mexer no provider de geração:

```bash theme={"system"}
export CHATCLI_IMAGE_PROVIDER=xai            # gera com Aurora/grok
export CHATCLI_IMAGE_EDIT_PROVIDER=sdwebui   # mas edita no SD WebUI local (keyless)
```

Se nenhum editor estiver disponível, o tool mostra um erro claro listando os backends que editam e como configurá-los.

***

## Modelos & configuração por comando

```text theme={"system"}
@image models                         # catálogo + modelos da sua conta OpenAI
/model-image grok-2-image             # define o modelo de imagem (vale p/ gen e edit)
/config image                         # panorama (backend, api, modelo, url, edit-provider)
/config image provider responses      # troca o backend
/config image api responses           # OpenAI: Images vs Responses
/config image model gpt-5.5           # define o modelo
/config image reset                   # limpa os overrides
```

Catálogo (resumo): 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` (gerar) / `gemini-2.5-flash-image` (editar); xAI `grok-2-image`; Bedrock `amazon.nova-canvas-v1:0`, `stability.stable-image-core-v1:1`, `stability.sd3-5-large-v1:0`.

***

## Formatos & detalhes

* **OpenAI edits** aceita `image/jpeg`, `image/png`, `image/webp` (não `gif`). O `Content-Type` do part multipart é enviado corretamente a partir dos bytes da imagem.
* **SD WebUI img2img** usa `denoising_strength` (mapeado de `strength`); default `0.6` (mudança visível preservando a estrutura).
* **Bedrock Stability** usa `mode: image-to-image` + `strength`; **Nova/Titan** usam `IMAGE_VARIATION` com `similarityStrength`.

***

## Privacidade & custo

* **Stable Diffusion WebUI local** é keyless, gera **e** edita na sua máquina — ideal para privacidade e custo zero.
* Backends de nuvem usam a chave do **próprio usuário**.
* Confirme antes de gerar/editar lotes grandes; mencione o custo quando aplicável.

***

## Relacionado

* [Entrada de Imagem (Visão)](/pt/features/vision-input) — o modelo **vê** imagens que você anexa
* [Text-to-Speech & Voz](/pt/features/text-to-speech)
* [Chat Gateway](/pt/features/chat-gateway)