> ## 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-2`).
4. `CHATCLI_IMAGE_PROVIDER=responses` (ou `openai` + `CHATCLI_IMAGE_API=responses`) → **OpenAI Responses API**, onde um modelo de chat como **`gpt-5.6-sol`** gera a imagem via a tool `image_generation`.
5. `GOOGLEAI_API_KEY`/`GEMINI_API_KEY` → **Google nativo** (Gemini image / "Nano Banana" `:generateContent`, gera **e** edita; default `gemini-3.1-flash-image` — a família Imagen `:predict` foi desligada pelo Google em 17/08/2026).
6. `XAI_API_KEY` → **xAI Grok Imagine nativo** (shape OpenAI, omite `size`; default `grok-imagine-image-2.0`). **Só gera.**
7. `CHATCLI_IMAGE_PROVIDER=bedrock` → **AWS Bedrock** (Stability / Nova Canvas 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-2`) | ✅ | ✅ | `/images/edits` (multipart) |
| **Self-hosted** (LocalAI…) | ✅ | ✅ | se expõe `/images/edits` |
| **Google** (Gemini image) | ✅ | ✅ | `:generateContent` com imagem inline |
| **Bedrock** (Stability / Nova) | ✅ | ✅ | Stability `image-to-image` / Nova `IMAGE_VARIATION` |
| xAI (Grok Imagine) | ✅ | ❌ | 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 Grok Imagine
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-imagine-image-2.0   # 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.6-sol       # define o modelo
/config image reset                   # limpa os overrides
```

Catálogo (resumo, ago/2026): OpenAI Images `gpt-image-2` (default; os antigos `gpt-image-1`/`1.5`/`1-mini` estão deprecados e desligam no fim de 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` desliga em 02/10/2026; Imagen foi desligado em 17/08/2026); 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` (legado, EOL 30/09/2026).

***

## 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 Canvas** (legado) usa `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/usage/vision-input) — o modelo **vê** imagens que você anexa
* [Text-to-Speech & Voz](/pt/gateway/text-to-speech)
* [Chat Gateway](/pt/gateway/chat-gateway)


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