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

# Entrada de Imagem (Visão)

> O modelo VÊ imagens que você anexa — em chat, coder, agent e nos canais do gateway. Multimodal nativo nos providers com visão, com describe-fallback automático para os demais.

Além de **gerar** imagens, o ChatCLI deixa o modelo **ver e entender** imagens que você anexa — e responder com base nelas. Funciona em **chat, `/coder`, `/agent`, one-shot (`-p`)** e nos **canais do gateway** (Telegram, WhatsApp, Slack, Discord, webhook).

***

## Como anexar

Use o `@file` apontando para uma imagem — ele detecta o tipo e anexa como entrada de visão (não inlina como texto):

```text theme={"system"}
@file diagrama.png o que esse fluxo faz?
@file ~/Downloads/erro.jpg por que esse stacktrace acontece?
@file print.png            # só a imagem, sem texto, também funciona
```

Formatos suportados: **PNG, JPEG, GIF, WebP**. Caminho local ou imagem dentro de um diretório. Imagens com extensão errada ainda são detectadas pelo conteúdo (sniff de MIME).

<Info>
  **Chat é tool-less por design** — anexar imagem em chat funciona (é anexo, não tool). Para **gerar/editar** imagem, use `/coder` ou `/agent` com o tool [`@image`](/pt/features/image-generation).
</Info>

***

## Estratégia híbrida (B + A)

O ChatCLI decide automaticamente, olhando a capability `vision` do **modelo ativo** no catálogo:

* **Modelo com visão** (GPT-4o/4.1/5.x, **Claude** 3+/4.x, Gemini, Kimi, GLM, Bedrock Claude…) → a imagem vai **nativa**, o modelo vê os pixels de verdade. *(Caminho B.)*
* **Modelo sem visão** → **describe-fallback**: um modelo com visão descreve a imagem e o texto entra no prompt, para que um modelo text-only ainda raciocine sobre o conteúdo. *(Caminho A.)*
* **Nenhum modelo com visão disponível** → aviso claro e a resposta segue só com texto (nunca quebra).

Nenhuma variável é necessária — `@file imagem` simplesmente funciona. `CHATCLI_VISION_PROVIDER`/`CHATCLI_VISION_MODEL` são apenas overrides do legendador do fallback (ex.: `gpt-4o-mini` como legendador barato).

### Modelos com visão fora do catálogo

Modelos pegos via API (`/models` do provider) podem não ter entrada no catálogo. A decisão é **em camadas** (`CHATCLI_VISION_INPUT`):

1. **Override** `CHATCLI_VISION_INPUT=native|describe|off` — controle explícito.
2. **Catálogo** (`vision` capability) — autoritativo pros conhecidos.
3. **Heurística conservadora** — se o **id** carrega marcador inequívoco de visão (`-vl`, `vl-`, `vision`, `pixtral`, `llava`, `internvl`, `qwen-vl`, `omni`, `multimodal`), trata como **nativo**. Esses nomes só existem em modelos multimodais → \~zero falso-positivo.
4. Senão → describe-fallback.

A heurística casa só marcadores explícitos, **nunca prefixos de família** (que têm exceções text-only como `claude-3-5-haiku`/`o3-mini`), então nunca envia bloco de imagem pra um modelo que quebraria. Sabe que seu modelo off-catalog vê? `CHATCLI_VISION_INPUT=native`.

***

## Cobertura por provider (visão nativa)

A serialização da imagem é feita por um helper compartilhado, em **6 dialetos** cobrindo os providers vision-capable:

| Dialeto                 | Providers                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| OpenAI `image_url`      | OpenAI, xAI, Z.AI, OpenRouter, Copilot, GitHub Models, Moonshot, MiniMax, Bedrock-OpenAI |
| Anthropic blocks        | Anthropic (API-key + OAuth), Bedrock-Claude, MiniMax-Anthropic                           |
| Gemini `inline_data`    | Google Gemini                                                                            |
| Bedrock SDK             | Bedrock Converse                                                                         |
| Ollama `images[]`       | Ollama                                                                                   |
| Responses `input_image` | OpenAI Responses                                                                         |

O gate é genérico: `catalog.HasCapability(provider, modelo, "vision")`. Providers de API text-only (ex.: StackSpot) caem automaticamente no describe-fallback.

***

## No gateway (canais de mensageria)

**Receber imagem** — mande uma foto no Telegram/WhatsApp/etc. e o gateway baixa, depois o modelo configurado vê (nativo ou describe-fallback, mesma lógica acima). Mensagens **só com imagem** (sem texto) ganham um pedido padrão de análise.

**Enviar imagem** — se o agent **gerou/editou** uma imagem durante a resposta (via [`@image`](/pt/features/image-generation)), ela é anexada automaticamente na resposta, em adapters que suportam foto.

| Variável                          | Função                                                    | Padrão |
| --------------------------------- | --------------------------------------------------------- | ------ |
| `CHATCLI_GATEWAY_IMAGE_REPLY`     | Anexa imagem gerada/editada na resposta: `auto` / `never` | `auto` |
| `CHATCLI_GATEWAY_MAX_IMAGE_BYTES` | Limite de download da imagem recebida (bytes)             | 20 MB  |

***

## Configuração

```text theme={"system"}
/config integrations          # mostra CHATCLI_VISION_*, CHATCLI_GATEWAY_IMAGE_REPLY etc.
```

| Variável                      | Função                                           | Padrão |
| ----------------------------- | ------------------------------------------------ | ------ |
| `CHATCLI_VISION_INPUT`        | Modo: `auto`/`native`/`describe`/`off`           | `auto` |
| `CHATCLI_VISION_PROVIDER`     | Provider do describe-fallback                    | (auto) |
| `CHATCLI_VISION_MODEL`        | Modelo do describe-fallback                      | (auto) |
| `CHATCLI_VISION_COMPRESS`     | Compressão de imagem antes do envio (`on`/`off`) | `on`   |
| `CHATCLI_VISION_MAX_EDGE`     | Cap da maior aresta em px                        | `1568` |
| `CHATCLI_VISION_JPEG_QUALITY` | Qualidade JPEG do re-encode (1–100)              | `82`   |

***

## Compressão de imagem (antes do envio)

Quando a visão nativa está ativa, o ChatCLI **encolhe a imagem** antes de mandá-la ao modelo — keyless e puro-Go (sem dependência nova, sem cgo). Faz parte da [Compressão de Contexto](/pt/features/context-compression):

* **Downscale** da maior aresta para `CHATCLI_VISION_MAX_EDGE` (1568px). Os provedores já reduzem imagens maiores server-side para esse tamanho ao contar tokens, então isso é **token-equivalente** — só evita subir pixels que seriam descartados — e para imagens acima do cap **reduz os tokens de visão cobrados**.
* **Re-encode JPEG** de fotos (qualidade `CHATCLI_VISION_JPEG_QUALITY`), bem menor que PNG, preservando transparência (imagens com alpha continuam PNG).
* **Seguro por construção**: nunca infla o payload e deixa formatos que não consegue round-trip (GIF animado, WebP) intactos. Imagens só-URL passam sem alteração.

Desative com `CHATCLI_VISION_COMPRESS=off`.

***

## Notas

* Imagens custam **tokens de prompt** (uma imagem grande pode valer centenas/milhares de tokens). Confirme antes de anexar lotes grandes em modelos pagos.
* A imagem permanece no histórico e é reenviada nos turnos seguintes (comportamento multimodal padrão).
* Para forçar um legendador específico no fallback: `CHATCLI_VISION_PROVIDER=openai CHATCLI_VISION_MODEL=gpt-4o-mini`.

***

## Relacionado

* [Geração e Edição de Imagem (@image)](/pt/features/image-generation) — o modelo **cria/edita** imagens
* [Chat Gateway](/pt/features/chat-gateway)
* [Respostas em Voz](/pt/features/voice-replies)