# Imagem

> Gere, transforme, edite, componha e descreva imagens e crie máscaras num assistente de IA com as ferramentas do Nodaro: parâmetros, padrões e créditos.

Source: https://nodaro.ai/pt-BR/docs/mcp/tools/image

As **ferramentas de imagem** permitem que um assistente crie e altere imagens no Nodaro. Com elas, ele pode gerar a partir de um prompt, transformar ou editar uma imagem existente, recortar uma máscara, compor várias imagens ou camadas e descrever o que uma imagem mostra. Cada ferramenta inicia um job e retorna o ID dele, e o resultado é salvo na sua biblioteca. Todas as ferramentas de imagem precisam da permissão `workflows:execute`.

| Ferramenta | O que faz | Créditos |
| --- | --- | --- |
| [`generate_image`](#generate_image) | Texto para imagem, com referências e inpainting opcional | O preço do modelo |
| [`modify_image`](#modify_image) | Edita, muda o estilo e transforma uma imagem existente | O preço do modelo |
| [`image_to_image`](#image_to_image) | Imagem para imagem guiada por prompt, com máscaras e várias referências | O preço do modelo |
| [`edit_image`](#edit_image) | Upscale, remoção de fundo e edições pontuais | O preço da operação |
| [`generate_mask`](#generate_mask) | Uma máscara em preto e branco do que você descrever | 55 |
| [`image_collage`](#image_collage) | De 2 a 30 imagens numa única imagem grande | 22 em 2K, 44 em 4K |
| [`image_overlay`](#image_overlay) | Logos, textos, QR codes e formas posicionados numa imagem, sem IA | 11, mais com tamanhos extras |
| [`suggest_overlay_placement`](#suggest_overlay_placement) | Onde um logo ou um texto deve ficar numa imagem | Uma descrição de imagem |
| [`image_to_text`](#image_to_text) | Uma descrição ou uma resposta sobre uma imagem | 4 com o modelo padrão |
| [`save_image_defaults`](#save_image_defaults) | O seu modelo e as suas configurações de imagem padrão | Grátis |

## `generate_image`
Cria uma imagem a partir de um prompt de texto com um dos modelos de imagem do Nodaro. É a ferramenta por trás de pedidos como “faça uma imagem de…”, e funciona como o nó [**Gerar imagem** (Generate Image)](https://nodaro.ai/docs/nodes/image/generate-image).

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo na resolução ou na qualidade escolhida.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `prompt` | string | A descrição da imagem, com até 4.000 caracteres. Obrigatório, a menos que uma predefinição o forneça. |
| `model` | string | O ID do modelo. Padrão: `nano-banana-2`. Um ID desconhecido volta ao padrão. Veja [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models). |
| `aspect_ratio` | string | Por exemplo `16:9`, `9:16`, `1:1`, `4:3`, `3:4` ou `21:9`. Padrão: `16:9`. Formas como `16x9` são aceitas, e uma proporção que o modelo não aceita é trocada por uma que ele aceita. |
| `resolution` | string | `1K`, `2K` ou `4K`, nos modelos compatíveis. É usado o valor compatível mais próximo. |
| `quality` | string | `medium` ou `high`, nos modelos que têm configuração de qualidade. |
| `negative_prompt` | string | O que evitar, com até 2.000 caracteres. |
| `reference_image_urls` | array | Até 14 imagens de referência, como URLs ou IDs do Nodaro, para manter uma pessoa, um personagem, um produto ou um estilo. A resposta confirma quantas foram anexadas. |
| `presetId` | string | Uma predefinição de [`list_node_presets`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_node_presets). Os campos que você informa a substituem. |
| `structured` | object | Detalhes estruturados adicionados ao prompt: `person` (idade, gênero, expressão, olhos, cabelo, profissão), `styling` (estética, look de cor, iluminação, clima), `setting` (atmosfera, fundo, época), `camera` (formato, enquadramento, movimento), `lens` (abertura, distância focal) e `mood`. |
| `described_references` | array | Até 10 itens `{ name, description }` para um assunto que você consegue nomear, mas do qual não tem imagem. Cada item vira uma linha do prompt, para que o nome no seu prompt chegue ao modelo como um assunto descrito. |
| `connected_references`, `reference_order` | array | Avançado. Referências rotuladas e ordenadas, no próprio formato do editor, até 14. |
| `base_image_url`, `mask_url` | string | Inpainting: a imagem a editar e uma máscara, em que o branco é alterado e o preto é mantido. A área mascarada é gerada de novo e recolocada sobre a imagem. |
| `strength` | number | Para inpainting, de 0 (sutil) a 1 (repintura completa), nos modelos compatíveis. |
| `guidance_scale` | number | De 0 a 20, nos modelos compatíveis. |

**Retorna:** um ID de job. Nos clientes com MCP Apps, o cartão mostra a imagem quando ela fica pronta.

## `modify_image`
Edita, muda o estilo ou transforma uma imagem existente com um prompt: trocar uma cor, substituir um fundo, aplicar um estilo, estender o quadro ou repintar parte dele. Funciona como o nó [**Modificar imagem** (Modify Image)](https://nodaro.ai/docs/nodes/image/modify-image).

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `prompt` | string | **Obrigatório.** A alteração que você quer, com até 8.000 caracteres. |
| `image_url` ou `image_asset_id` | string | **Obrigatório, um dos dois.** Uma URL `https` pública ou o ID de um job do Nodaro cujo resultado é uma imagem. |
| `model` | string | Padrão: `nano-banana-2`. Use `nano-banana-pro` para manter um rosto ou um personagem igual em várias edições e para texto na imagem, e `gpt-image-2-i2i` para edições com muito texto. Um ID desconhecido volta ao padrão. |
| `aspect_ratio` | string | O formato da saída. Um valor não compatível é trocado por outro. |
| `resolution` | string | É usado o valor compatível mais próximo. |
| `quality` | string | `medium`, `high` ou `basic`, nos modelos que têm essa configuração. |
| `negative_prompt` | string | O que evitar, com até 2.000 caracteres. |
| `structured` | object | Os mesmos detalhes estruturados de `generate_image`. |

**Retorna:** um ID de job.

## `image_to_image`
Transforma uma imagem com um prompt, com opções de máscara e de composição de várias referências numa única imagem.

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `prompt` | string | **Obrigatório.** A transformação, com até 2.000 caracteres. |
| `image_url` ou `image_asset_id` | string | A imagem de origem. |
| `model` | string | Padrão: `nano-banana`. Outros incluem `nano-banana-2`, `flux-kontext` para edições fotorrealistas, `gpt-image-i2i` para repinturas criativas, `flux-i2i` e `ideogram-remix`. Um ID desconhecido volta para `nano-banana`. |
| `reference_image_urls` | array | Até 13 imagens de referência extras, como URLs ou IDs do Nodaro, para modelos que aceitam várias referências. |
| `mask_url` | string | Uma máscara de inpainting: o branco é alterado, o preto é mantido. |
| `strength` | number | De 0 (sutil) a 1 (repintura completa). |
| `aspect_ratio` | string | O formato da saída. |
| `resolution` | string | `1K`, `2K` ou `4K`. |
| `quality` | string | `medium`, `high` ou `basic`. |
| `seed` | integer | Uma seed fixa, nos modelos compatíveis. |
| `negative_prompt` | string | O que evitar, com até 5.000 caracteres. |

**Retorna:** um ID de job.

## `edit_image`
Faz o upscale de uma imagem, remove o fundo dela ou aplica uma edição pontual. Escolha a operação com `model`.

**Permissão:** `workflows:execute`. **Créditos:** o preço da operação, na tabela abaixo.

| `model` | Operação | Requer |
| --- | --- | --- |
| `recraft-upscale` (padrão) | Um upscale nítido | A imagem |
| `topaz-image-upscale` | Upscale de 1, 2 ou 4 vezes | A imagem e `upscale_factor` |
| `recraft-remove-bg` | Remove o fundo e retorna um PNG com transparência | A imagem |
| `nano-banana-edit` | Uma edição por prompt, dentro de uma máscara ou fora do quadro | A imagem, `prompt` e um `mask_url` opcional |
| `grok-upscale` | Um upscale criativo de uma geração anterior do Grok | `kie_task_id` |
| `grok-2-segment` | Um mapa grátis das regiões nomeadas de uma imagem anterior do Grok Imagine 2 | `kie_task_id` |
| `grok-2-edit` | Uma edição por prompt de uma imagem anterior do Grok Imagine 2, opcionalmente só em algumas regiões | `kie_task_id`, `prompt` e `mask_indexes` opcional |

| Model | Maker | Modes | Credits | Details |
| --- | --- | --- | --- | --- |
| [Recraft Crisp Upscale](https://nodaro.ai/docs/models/image/recraft-crisp-upscale) | Recraft | Image upscaling | 3 | Light-weight image upscale (Recraft Crisp). |
| [Topaz Image Upscale](https://nodaro.ai/docs/models/image/topaz-image-upscale) | Topaz | Image upscaling | a partir de 28 | High-quality image upscale at 1x (enhance only), 2x or 4x. Best for production-ready output. |
| [Recraft Remove BG](https://nodaro.ai/docs/models/image/recraft-remove-bg) | Recraft | Background removal | 4 | Remove image background. Cheap utility. |
| [Nano Banana Edit](https://nodaro.ai/docs/models/image/nano-banana-edit) | Google | Image editing | 11 | Image-to-image edits via Google's Nano Banana family. Good general-purpose editor. |
| [Grok Upscale](https://nodaro.ai/docs/models/image/grok-upscale) | xAI | Image upscaling | 28 | Upscale a previously-generated Grok image. Requires the prior task id. |
| [Grok Imagine 2 Segment Map](https://nodaro.ai/docs/models/image/grok-imagine-2-segment-map) | xAI | Image editing | 0 | FREE semantic segment map of a prior grok-2 generation — named region masks whose indexes feed grok-2-edit's region targeting. |
| [Grok Imagine 2 Edit](https://nodaro.ai/docs/models/image/grok-imagine-2-edit) | xAI | Image editing | 11 | Prompt-edit a prior grok-2 generation by task id. Optional mask indexes (from grok-2-segment) restrict the edit to named regions. |

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `model` | string | A operação, da tabela acima. Padrão: `recraft-upscale`. |
| `image_url` ou `image_asset_id` | string | A imagem de origem, em todas as operações, exceto as três do Grok. |
| `prompt` | string | Obrigatório para `nano-banana-edit` e `grok-2-edit`. Até 2.000 caracteres. |
| `mask_url` | string | Para `nano-banana-edit`: o branco é alterado. |
| `upscale_factor` | string | Para `topaz-image-upscale`: `1`, `2` ou `4`. Padrão: `2`. |
| `target_resolution` | string | Uma forma mais antiga de definir o fator de upscale de `topaz-image-upscale`: `2K` equivale a `2`, e `4K` e `8K` equivalem a `4`. Use `upscale_factor` no lugar. |
| `kie_task_id` | string | Para as operações do Grok: o ID da tarefa da geração anterior do Grok. `get_job` o retorna como `kieTaskId` na saída da geração. |
| `mask_indexes` | array | Para `grok-2-edit`: os valores de `index` das regiões a alterar, vindos de uma execução de `grok-2-segment`. |
| `negative_prompt`, `seed`, `style` | | Opcionais, nas operações que os usam. |

Para editar só algumas regiões de uma imagem do Grok Imagine 2, trabalhe em duas etapas. Primeiro, execute `grok-2-segment` com o `kie_task_id` da imagem e leia as regiões nomeadas no campo `segments` do job. Depois, execute `grok-2-edit` com o mesmo `kie_task_id`, um prompt e os `mask_indexes` das regiões a alterar. O mapa de regiões é grátis.

**Retorna:** um ID de job.

## `generate_mask`
Cria uma máscara em preto e branco do que você descrever, por exemplo “the person” ou “sky and clouds”. O branco é a área selecionada. Use a máscara com `image_to_image`, `edit_image` ou os campos de inpainting de `generate_image`. Funciona como o nó [**Gerar máscara** (Generate Mask)](https://nodaro.ai/docs/nodes/image/generate-mask).

**Permissão:** `workflows:execute`. **Créditos:** 55.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `prompt` | string | **Obrigatório.** O que selecionar, com até 500 caracteres. |
| `image_url` ou `image_asset_id` | string | A imagem de origem. |
| `threshold` | number | A confiança da detecção, de 0 a 1. Padrão: `0.3`. |

**Retorna:** um ID de job. O resultado é uma máscara PNG.

## `image_collage`
Junta de 2 a 30 imagens numa única imagem grande. Nenhuma imagem é cortada: o layout `smart` as organiza em linhas, cada uma no próprio formato, e o layout `grid` usa células iguais, com o espaço vazio preenchido pela cor de fundo. Funciona como o nó [**Colagem de imagens** (Image Collage)](https://nodaro.ai/docs/nodes/image/image-collage) e serve bem para storyboards e folhas de contato.

**Permissão:** `workflows:execute`. **Créditos:** 22 em `2K`, 44 em `4K`.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `images` | array | **Obrigatório.** De 2 a 30 itens, cada um `{ url }` ou `{ asset_id }`. Um item pode acrescentar `size`, um tamanho relativo para o layout smart (`0` automático, `1` grande, `2` médio, `3` pequeno), e `label`, uma legenda de até 80 caracteres. |
| `layout` | string | `smart` (padrão) ou `grid`. |
| `resolution` | string | O lado maior: `2K` ou `4K` (padrão, 3840 pixels). |
| `aspect_ratio` | string | Qualquer `W:H`, como `16:9` ou `9:16`. Padrão: `4:3`. Exata no `grid`; uma meta no `smart`, em que a altura acompanha as linhas. |
| `gap` | integer | O espaço entre as imagens e em volta delas, de 0 a 200 pixels. Padrão: `24`. |
| `background_color` | string | Uma cor `#RRGGBB`. Padrão: `#ffffff`. |
| `numbered` | boolean | Carimba 1, 2, 3 e assim por diante no canto de cada imagem, na ordem de `images`. |
| `badge_position` | string | O canto dos números e das legendas: `top-left` (padrão) ou `top-right`. |

**Retorna:** um ID de job.

## `image_overlay`
Posiciona de 1 a 12 camadas sobre uma imagem base, com precisão de pixel: logos, recortes, textos, QR codes e formas. Nenhum modelo de IA é executado, então o resultado é sempre o mesmo. Funciona como o nó [**Sobreposição em imagem** (Image Overlay)](https://nodaro.ai/docs/nodes/image/image-overlay), cuja página documenta todas as opções.

**Permissão:** `workflows:execute`. **Créditos:** 11, e um pouco mais por tamanho extra de plataforma em `variants`, como no nó [Sobreposição em imagem](https://nodaro.ai/docs/nodes/image/image-overlay#credits).

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `image_url` ou `image_asset_id` | string | A imagem base. |
| `layers` | array | **Obrigatório.** De 1 a 12 camadas. Veja os campos de camada abaixo. A ordem do array é a ordem de empilhamento, a menos que uma camada defina `z_index`. |
| `canvas` | object | Um tamanho de saída, `width` e `height` de 16 a 8192 pixels, com uma `background_color`. A base é encaixada nele com `base_fit`, `contain` ou `cover`. Omita-o para manter o tamanho da imagem base. |
| `variants` | array | Tamanhos extras de plataforma para renderizar de uma vez: `youtube-thumbnail`, `youtube-banner`, `linkedin-company`, `linkedin-personal`, `x-header`, `facebook-cover`, `instagram-post`, `instagram-portrait`, `instagram-story`, `open-graph`, `presentation`, `a4-print`. |
| `qr_text` | string | Preenche cada camada de QR cujo `qr.fromInput` seja `true`. |
| `mask_mode` | string | A máscara que o job também retorna como `maskUrl`, em que o branco pode mudar: `around` (padrão, um anel em volta das camadas para um acabamento com IA), `layers`, `outside` ou `none`. |
| `mask_spread` | integer | A largura do anel `around`, de 1 a 400 pixels. Padrão: `48`. |
| `output_format` | string | `png` (padrão, mantém a transparência), `jpg` ou `webp`. |

Os principais campos de camada:

| Campo da camada | Observações |
| --- | --- |
| `kind` | `image` (padrão, requer `url` ou `asset_id`), `text`, `qr` ou `shape`. |
| `anchor` | Uma de 9 posições, de `top-left` a `bottom-right`. Padrão: `center`. |
| `x`, `y` | O deslocamento em relação à âncora, em porcentagem da largura e da altura da base. Um valor negativo numa âncora à direita ou embaixo move a camada para dentro. |
| `width`, `height` | Em porcentagem da largura e da altura da base. Largura padrão: 25%. A altura acompanha o formato da camada, a menos que você a defina. |
| `opacity`, `rotation`, `blend` | Opacidade de 0 a 1, rotação em graus e mesclagem `over`, `multiply` ou `screen`. |
| `fit`, `shadow`, `rounded_corners`, `z_index` | Como a camada preenche a caixa dela (`contain`, `cover` ou `stretch`), uma sombra projetada, cantos arredondados e a ordem de empilhamento. |
| `effects` | Só para camadas de imagem: uma máscara circular, bordas suavizadas, um contorno ou um brilho. |
| `text` | Para uma camada de texto: o `text`, um `fontId` (`inter`, `montserrat`, `space-grotesk`, `playfair-display`, `oswald`, `bebas-neue`, `anton`, `pacifico`, `rubik` ou `heebo`; `rubik` e `heebo` servem para hebraico), um `fontSize` em porcentagem da altura da base, `fontWeight`, `color`, `align`, `letterSpacing`, `lineHeight`, `uppercase`, um contorno e uma caixa de fundo. |
| `qr` | Para uma camada de QR: o `text` a codificar, ou `fromInput: true`, além de cores e margem. |
| `shape` | Para uma camada de forma: `rect`, `rounded`, `pill`, `circle`, `ribbon`, `triangle`, `diamond`, `hexagon`, `star`, `burst` ou `arrow`, com uma cor e um contorno. |

Uma marca d’água no canto inferior direito é `anchor: "bottom-right"`, `x: -4`, `y: -6`, `width: 12`. Os logos em SVG são renderizados nítidos no tamanho de destino.

**Retorna:** um ID de job. O resultado traz a imagem, `maskUrl`, a `width` e a `height` dela e `variants`, uma lista de `{ id, label, width, height, url }`.

## `suggest_overlay_placement`
Pergunta a um modelo de visão onde uma camada deve ficar sobre uma imagem base. O modelo analisa a imagem e mantém a camada longe de rostos, do assunto principal e de texturas carregadas. Nada é composto: passe a resposta para `image_overlay`.

**Permissão:** `workflows:execute`. **Créditos:** uma descrição de imagem, o preço de `image_to_text`.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `image_url` ou `image_asset_id` | string | A imagem base. |
| `intent` | string | O que a camada é, como um logo, um título, um selo de preço ou um QR code. Até 300 caracteres. Padrão: um logo. |
| `layer_aspect` | number | A largura da camada dividida pela altura dela, de 0,05 a 20. Padrão: `1`, um quadrado. |
| `safe_area` | object | A área sempre visível, em frações do canvas: `x`, `y`, `w`, `h`. A camada fica dentro dela. |

**Retorna:** `anchor`, `x`, `y` e `width`, nas mesmas unidades de porcentagem de `image_overlay`, e um `reason` de uma frase.

## `image_to_text`
Descreve uma imagem, ou responde a uma pergunta sobre ela, com um modelo de visão. Use-a para legendas, texto alternativo, análise de cena ou uma pergunta específica, como “list all the text in the image”. Funciona como o nó [**Descrever imagem** (Describe Image)](https://nodaro.ai/docs/nodes/image/describe-image).

**Permissão:** `workflows:execute`. **Créditos:** 4 com o modelo padrão; o preço acompanha o nível do modelo.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `image_url` ou `image_asset_id` | string | A imagem a descrever. |
| `detail_level` | string | `brief`, `detailed` (padrão) ou `comprehensive`. |
| `custom_prompt` | string | Uma pergunta específica em vez de uma descrição geral, com até 2.000 caracteres. |
| `llmModel` | string | O modelo de visão, um dos IDs de LLM que a ferramenta lista. |
| `reasoning_effort` | string | De `none` a `max`. `xhigh` e `max` são cobrados um nível acima, até o limite do premium. |
| `advanced_mode`, `temperature`, `max_tokens` | | Somente modelos Gemini, como nas [ferramentas de prompt](https://nodaro.ai/docs/mcp/tools/prompts-and-text#enhance_prompt). É cobrado um nível acima, até o limite do premium. |

**Retorna:** um ID de job. O texto fica na saída do job, e o cartão o mostra com um botão **Copy**.

## `save_image_defaults`
Salva as suas configurações de imagem preferidas, para que as próximas chamadas de `generate_image` as usem quando você não disser outra coisa. Só mudam os campos que você informar. Nos clientes com MCP Apps, o chip **Save as default** num cartão de imagem chama esta ferramenta.

**Permissão:** `workflows:execute`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `model` | string or null | O seu modelo padrão. `null` o apaga e volta ao padrão do catálogo. |
| `aspect_ratio` | string or null | A sua proporção padrão. |
| `resolution` | string or null | A sua resolução padrão. |
| `quality` | string or null | A sua qualidade padrão. |

**Retorna:** uma confirmação.

## Frequently asked questions

### Qual modelo generate_image usa por padrão?

O Nano Banana 2. Passe model com outro ID de list_models para trocá-lo, por exemplo nano-banana-pro para texto legível ou gpt-image-2-5-flare para iterações rápidas. Um ID desconhecido volta ao padrão sem erro.

### Como mantenho a mesma pessoa em várias imagens?

Passe as fotos da pessoa em reference_image_urls, até 14 URLs ou IDs do Nodaro, e a resposta confirma quantas foram anexadas. Para um personagem salvo, passe o retrato aprovado que get_character retorna.

### Como removo o fundo ou faço o upscale de uma imagem pelo MCP?

Use edit_image. Defina model como recraft-remove-bg para um PNG transparente, ou como recraft-upscale ou topaz-image-upscale para fazer o upscale. Nenhum deles precisa de prompt.

### Um assistente pode colocar um logo ou um texto numa imagem sem IA?

Sim. image_overlay posiciona imagens, textos, QR codes e formas sobre uma imagem base, com precisão de pixel e sem nenhum modelo, e custa 11 créditos. suggest_overlay_placement pode sugerir antes onde um logo deve ficar.

### Quanto custa gerar uma imagem pelo MCP?

O mesmo que no editor. O preço depende do modelo e da resolução ou qualidade dele; list_models e a página de cada modelo listam os créditos exatos.