> ## 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/tools/image-generation).
</Info>

***

## `@view` — olhar uma imagem no meio da tarefa

O `@file` anexa uma imagem quando **você** inicia um turno. Mas dentro de `/agent` e `/coder`, o modelo muitas vezes produz uma imagem **ele mesmo** — um screenshot do [`@browser`](/pt/tools/browser-automation), um diagrama renderizado — e precisa vê-la para continuar. Isso é o `@view`:

```text theme={"system"}
@view {"cmd":"view","args":{"file":"/tmp/chatcli-browser/screenshot-1.png"}}
@view /tmp/shot.png          # caminho puro também funciona
```

O `@view` carrega uma imagem local (**PNG, JPEG, GIF, WebP**) pelo **mesmo pipeline de visão** do `@file` — caps de tamanho, compressão, multimodal nativo ou describe-fallback — e a **estagia** para ser anexada à conversa no **próximo turno**. O modelo então analisa o que está visível. É **read-only** e disponível em `/agent` e `/coder` (em chat puro, use `@file`).

O par natural é com o `@browser`: **tire um screenshot da página e olhe para ele.**

```text theme={"system"}
@browser screenshot                         # captura a página atual → retorna um caminho
@view    /tmp/chatcli-browser/screenshot-*.png   # o modelo vê de verdade
```

<Note>
  **PDFs ainda não são suportados** — renderize a página relevante para uma imagem (PNG/JPEG) primeiro e então use `@view`.
</Note>

***

## 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, 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/tools/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/context/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/tools/image-generation) — o modelo **cria/edita** imagens
* [Chat Gateway](/pt/gateway/chat-gateway)
* [Respostas em Voz](/pt/gateway/voice-replies)


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