# Image

> Generate, transform, edit, mask, composite and describe images from an AI assistant with the Nodaro image tools, their parameters, defaults and credits.

Source: https://nodaro.ai/docs/mcp/tools/image

The **image tools** let an assistant create and change images in Nodaro: generate from a prompt, transform or edit an existing image, cut a mask, composite several images or layers, and describe what an image shows. Each tool starts a job and returns its id, and the result is saved to your library. Every image tool needs the `workflows:execute` permission.

| Tool | What it does | Credits |
| --- | --- | --- |
| [`generate_image`](#generate_image) | Text to image, with references and optional inpainting | The model's price |
| [`modify_image`](#modify_image) | Edits, restyles and transforms an existing image | The model's price |
| [`image_to_image`](#image_to_image) | Prompt-guided image to image, with masks and several references | The model's price |
| [`edit_image`](#edit_image) | Upscale, background removal and targeted edits | The operation's price |
| [`generate_mask`](#generate_mask) | A black and white mask of what you describe | 50 |
| [`image_collage`](#image_collage) | 2 to 30 images in one large image | 20 at 2K, 40 at 4K |
| [`image_overlay`](#image_overlay) | Logos, text, QR codes and shapes placed on an image, without AI | 10, plus 2 per extra size |
| [`suggest_overlay_placement`](#suggest_overlay_placement) | Where a logo or text should sit on an image | One image description |
| [`image_to_text`](#image_to_text) | A description or answer about an image | 3 with the default model |
| [`save_image_defaults`](#save_image_defaults) | Your default image model and settings | Free |

## `generate_image`

Creates an image from a text prompt with one of Nodaro's image models. It is the tool behind requests such as "make an image of…", and it works like the [Generate Image](https://nodaro.ai/docs/nodes/image/generate-image) node.

**Permission:** `workflows:execute`. **Credits:** the price of the model at the chosen resolution or quality.

| Parameter | Type | Notes |
| --- | --- | --- |
| `prompt` | string | The description of the image, up to 4,000 characters. Required unless a preset supplies it. |
| `model` | string | The model id. Default `nano-banana-2`. An unknown id falls back to the default. See [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models). |
| `aspect_ratio` | string | For example `16:9`, `9:16`, `1:1`, `4:3`, `3:4` or `21:9`. Default `16:9`. Forms such as `16x9` are accepted, and a ratio the model does not support falls back to one it does. |
| `resolution` | string | `1K`, `2K` or `4K`, on models that support it. The nearest supported value is used. |
| `quality` | string | `medium` or `high`, on models that have a quality setting. |
| `negative_prompt` | string | What to avoid, up to 2,000 characters. |
| `reference_image_urls` | array | Up to 14 reference images, as URLs or Nodaro ids, to keep a person, character, product or style. The reply confirms how many were attached. |
| `presetId` | string | A preset from [`list_node_presets`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_node_presets). Fields you pass override it. |
| `structured` | object | Structured details added to the prompt: `person` (age, gender, expression, eyes, hair, profession), `styling` (aesthetic, color look, lighting, mood), `setting` (atmosphere, backdrop, era), `camera` (format, framing, motion), `lens` (aperture, focal length) and `mood`. |
| `described_references` | array | Up to 10 `{ name, description }` entries for a subject you can name but have no picture of. Each becomes a line of the prompt, so the name in your prompt reaches the model as a described subject. |
| `connected_references`, `reference_order` | array | Advanced. Labeled, ordered references in the editor's own format, up to 14. |
| `base_image_url`, `mask_url` | string | Inpainting: the image to edit and a mask, where white is changed and black is kept. The masked area is generated again and placed back over the image. |
| `strength` | number | For inpainting, from 0 (subtle) to 1 (full repaint), on models that support it. |
| `guidance_scale` | number | From 0 to 20, on models that support it. |

**Returns:** a job id. In clients with MCP Apps, the card shows the image when it is ready.

## `modify_image`

Edits, restyles or transforms an existing image with a prompt: change a color, swap a background, apply a style, extend or repaint part of the frame. It works like the [Modify Image](https://nodaro.ai/docs/nodes/image/modify-image) node.

**Permission:** `workflows:execute`. **Credits:** the price of the model.

| Parameter | Type | Notes |
| --- | --- | --- |
| `prompt` | string | **Required.** The change you want, up to 8,000 characters. |
| `image_url` or `image_asset_id` | string | **Required, one of the two.** A public `https` URL, or the id of a Nodaro job whose result is an image. |
| `model` | string | Default `nano-banana-2`. Use `nano-banana-pro` to keep a face or a character the same across several edits and for text in the image, and `gpt-image-2-i2i` for edits with a lot of text. An unknown id falls back to the default. |
| `aspect_ratio` | string | The output shape. An unsupported value falls back. |
| `resolution` | string | The nearest supported value is used. |
| `quality` | string | `medium`, `high` or `basic`, on models that have it. |
| `negative_prompt` | string | What to avoid, up to 2,000 characters. |
| `structured` | object | The same structured details as `generate_image`. |

**Returns:** a job id.

## `image_to_image`

Transforms an image with a prompt, with options for masks and for composing several references in one image.

**Permission:** `workflows:execute`. **Credits:** the price of the model.

| Parameter | Type | Notes |
| --- | --- | --- |
| `prompt` | string | **Required.** The transformation, up to 2,000 characters. |
| `image_url` or `image_asset_id` | string | The source image. |
| `model` | string | Default `nano-banana`. Others include `nano-banana-2`, `flux-kontext` for photorealistic edits, `gpt-image-i2i` for creative repaints, `flux-i2i` and `ideogram-remix`. An unknown id falls back to `nano-banana`. |
| `reference_image_urls` | array | Up to 13 extra reference images, as URLs or Nodaro ids, for models that take several references. |
| `mask_url` | string | An inpainting mask: white is changed, black is kept. |
| `strength` | number | From 0 (subtle) to 1 (full repaint). |
| `aspect_ratio` | string | The output shape. |
| `resolution` | string | `1K`, `2K` or `4K`. |
| `quality` | string | `medium`, `high` or `basic`. |
| `seed` | integer | A fixed seed, on models that support it. |
| `negative_prompt` | string | What to avoid, up to 5,000 characters. |

**Returns:** a job id.

## `edit_image`

Upscales an image, removes its background, or applies a targeted edit. Choose the operation with `model`.

**Permission:** `workflows:execute`. **Credits:** the price of the operation, in the table below.

| `model` | Operation | Needs |
| --- | --- | --- |
| `recraft-upscale` (default) | A sharp upscale | The image |
| `topaz-image-upscale` | Upscale by 1, 2 or 4 times | The image, and `upscale_factor` |
| `recraft-remove-bg` | Removes the background and returns a PNG with transparency | The image |
| `nano-banana-edit` | A prompt edit, inside a mask or outside the frame | The image, `prompt`, and an optional `mask_url` |
| `grok-upscale` | A creative upscale of an earlier Grok generation | `kie_task_id` |
| `grok-2-segment` | A free map of named regions of an earlier Grok Imagine 2 image | `kie_task_id` |
| `grok-2-edit` | A prompt edit of an earlier Grok Imagine 2 image, optionally only in some regions | `kie_task_id`, `prompt`, and optional `mask_indexes` |

| Model | Maker | Modes | Credits | Details |
| --- | --- | --- | --- | --- |
| [Recraft Crisp Upscale](https://nodaro.ai/docs/models/image/recraft-crisp-upscale) | Recraft | Image upscaling | 2 | Light-weight image upscale (Recraft Crisp). |
| [Topaz Image Upscale](https://nodaro.ai/docs/models/image/topaz-image-upscale) | Topaz | Image upscaling | from 25 | 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 | 3 | Remove image background. Cheap utility. |
| [Nano Banana Edit](https://nodaro.ai/docs/models/image/nano-banana-edit) | Google | Image editing | 10 | 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 | 25 | 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 | 10 | Prompt-edit a prior grok-2 generation by task id. Optional mask indexes (from grok-2-segment) restrict the edit to named regions. |

| Parameter | Type | Notes |
| --- | --- | --- |
| `model` | string | The operation, from the table above. Default `recraft-upscale`. |
| `image_url` or `image_asset_id` | string | The source image, for every operation except the three Grok ones. |
| `prompt` | string | Required for `nano-banana-edit` and `grok-2-edit`. Up to 2,000 characters. |
| `mask_url` | string | For `nano-banana-edit`: white is changed. |
| `upscale_factor` | string | For `topaz-image-upscale`: `1`, `2` or `4`. Default `2`. |
| `kie_task_id` | string | For the Grok operations: the task id of the earlier Grok generation. `get_job` returns it as `kieTaskId` in the generation's output. |
| `mask_indexes` | array | For `grok-2-edit`: the `index` values of the regions to change, from a `grok-2-segment` run. |
| `negative_prompt`, `seed`, `style` | | Optional, on the operations that use them. |

To edit only some regions of a Grok Imagine 2 image, work in two steps. First run `grok-2-segment` with the image's `kie_task_id`, and read the named regions from the job's `segments`. Then run `grok-2-edit` with the same `kie_task_id`, a prompt, and the `mask_indexes` of the regions to change. The region map is free.

**Returns:** a job id.

## `generate_mask`

Makes a black and white mask of what you describe, for example "the person" or "sky and clouds". White is the selected area. Use the mask with `image_to_image`, `edit_image` or the inpainting fields of `generate_image`. It works like the [Generate Mask](https://nodaro.ai/docs/nodes/image/generate-mask) node.

**Permission:** `workflows:execute`. **Credits:** 50.

| Parameter | Type | Notes |
| --- | --- | --- |
| `prompt` | string | **Required.** What to select, up to 500 characters. |
| `image_url` or `image_asset_id` | string | The source image. |
| `threshold` | number | The detection confidence, from 0 to 1. Default `0.3`. |

**Returns:** a job id. The result is a PNG mask.

## `image_collage`

Puts 2 to 30 images into one large image. No image is ever cropped: the `smart` layout arranges them in rows at their own shapes, and the `grid` layout uses equal cells with the empty space filled by the background color. It works like the [Image Collage](https://nodaro.ai/docs/nodes/image/image-collage) node, and suits storyboards and contact sheets.

**Permission:** `workflows:execute`. **Credits:** 20 at `2K`, 40 at `4K`.

| Parameter | Type | Notes |
| --- | --- | --- |
| `images` | array | **Required.** 2 to 30 items, each `{ url }` or `{ asset_id }`. An item can add `size`, a relative size for the smart layout (`0` auto, `1` big, `2` medium, `3` small), and `label`, a caption of up to 80 characters. |
| `layout` | string | `smart` (default) or `grid`. |
| `resolution` | string | The long edge: `2K`, or `4K` (default, 3,840 pixels). |
| `aspect_ratio` | string | Any `W:H`, such as `16:9` or `9:16`. Default `4:3`. Exact in `grid`; a target in `smart`, where the height follows the rows. |
| `gap` | integer | The space between images and around them, from 0 to 200 pixels. Default `24`. |
| `background_color` | string | A `#RRGGBB` color. Default `#ffffff`. |
| `numbered` | boolean | Stamps 1, 2, 3 and so on in the corner of each image, in the order of `images`. |
| `badge_position` | string | The corner of the numbers and labels: `top-left` (default) or `top-right`. |

**Returns:** a job id.

## `image_overlay`

Places 1 to 12 layers on a base image, pixel-exactly: logos, cut-outs, text, QR codes and shapes. No AI model runs, so the result is the same every time. It works like the [Image Overlay](https://nodaro.ai/docs/nodes/image/image-overlay) node, which documents every option.

**Permission:** `workflows:execute`. **Credits:** 10, plus 2 for each extra platform size in `variants`.

| Parameter | Type | Notes |
| --- | --- | --- |
| `image_url` or `image_asset_id` | string | The base image. |
| `layers` | array | **Required.** 1 to 12 layers. See the layer fields below. The array order is the stacking order unless a layer sets `z_index`. |
| `canvas` | object | An output size, `width` and `height` from 16 to 8,192 pixels, with a `background_color`. The base is placed into it with `base_fit`, `contain` or `cover`. Leave it out to keep the base image's size. |
| `variants` | array | Extra platform sizes to render at once: `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 | Fills every QR layer whose `qr.fromInput` is `true`. |
| `mask_mode` | string | The mask the job also returns as `maskUrl`, where white may change: `around` (default, a ring around the layers for an AI finish), `layers`, `outside` or `none`. |
| `mask_spread` | integer | The width of the `around` ring, from 1 to 400 pixels. Default `48`. |
| `output_format` | string | `png` (default, keeps transparency), `jpg` or `webp`. |

The main layer fields:

| Layer field | Notes |
| --- | --- |
| `kind` | `image` (default, needs `url` or `asset_id`), `text`, `qr` or `shape`. |
| `anchor` | One of 9 positions, from `top-left` to `bottom-right`. Default `center`. |
| `x`, `y` | The offset from the anchor, in percent of the base width and height. A negative value on a right or bottom anchor moves the layer inward. |
| `width`, `height` | In percent of the base width and height. Default width 25%. The height follows the layer's shape unless you set it. |
| `opacity`, `rotation`, `blend` | Opacity from 0 to 1, rotation in degrees, and blend `over`, `multiply` or `screen`. |
| `fit`, `shadow`, `rounded_corners`, `z_index` | How the layer fills its box (`contain`, `cover` or `stretch`), a drop shadow, rounded corners and the stacking order. |
| `effects` | Image layers only: a circle mask, a feather, a stroke or a glow. |
| `text` | For a text layer: the `text`, a `fontId` (`inter`, `montserrat`, `space-grotesk`, `playfair-display`, `oswald`, `bebas-neue`, `anton`, `pacifico`, `rubik` or `heebo`; `rubik` and `heebo` set Hebrew), a `fontSize` in percent of the base height, `fontWeight`, `color`, `align`, `uppercase`, an outline and a background box. |
| `qr` | For a QR layer: the `text` to encode, or `fromInput: true`, plus colors and margin. |
| `shape` | For a shape layer: `rect`, `rounded`, `pill`, `circle`, `ribbon`, `triangle`, `diamond`, `hexagon`, `star`, `burst` or `arrow`, with a color and an outline. |

A watermark in the bottom right corner is `anchor: "bottom-right"`, `x: -4`, `y: -6`, `width: 12`. SVG logos are rendered sharp at the target size.

**Returns:** a job id. The result carries the image, `maskUrl`, its `width` and `height`, and `variants`, a list of `{ id, label, width, height, url }`.

## `suggest_overlay_placement`

Asks a vision model where one layer should sit on a base image. The model looks at the picture and keeps the layer off faces, the subject and busy texture. Nothing is composited: pass the answer to `image_overlay`.

**Permission:** `workflows:execute`. **Credits:** one image description, the price of `image_to_text`.

| Parameter | Type | Notes |
| --- | --- | --- |
| `image_url` or `image_asset_id` | string | The base image. |
| `intent` | string | What the layer is, such as a logo, a headline, a price badge or a QR code. Up to 300 characters. Default: a logo. |
| `layer_aspect` | number | The layer's width divided by its height, from 0.05 to 20. Default `1`, a square. |
| `safe_area` | object | The area that is always visible, as fractions of the canvas: `x`, `y`, `w`, `h`. The layer stays inside it. |

**Returns:** `anchor`, `x`, `y` and `width` in the same percent units as `image_overlay`, and a one-sentence `reason`.

## `image_to_text`

Describes an image, or answers a question about it, with a vision model. Use it for captions, alt text, scene analysis or a specific question, such as "list all the text in the image". It works like the [Describe Image](https://nodaro.ai/docs/nodes/image/describe-image) node.

**Permission:** `workflows:execute`. **Credits:** 3 with the default model; the price follows the model's tier.

| Parameter | Type | Notes |
| --- | --- | --- |
| `image_url` or `image_asset_id` | string | The image to describe. |
| `detail_level` | string | `brief`, `detailed` (default) or `comprehensive`. |
| `custom_prompt` | string | A specific question instead of a general description, up to 2,000 characters. |
| `llmModel` | string | The vision model, one of the LLM ids the tool lists. |
| `reasoning_effort` | string | `none` to `max`. `xhigh` and `max` bill one tier higher. |
| `advanced_mode`, `temperature`, `max_tokens` | | Gemini models only, as on the [prompt tools](https://nodaro.ai/docs/mcp/tools/prompts-and-text#enhance_prompt). Bills one tier higher. |

**Returns:** a job id. The text is in the job's output, and the card shows it with a **Copy** button.

## `save_image_defaults`

Saves your preferred image settings, so later `generate_image` calls use them when you do not say otherwise. Only the fields you pass change. In clients with MCP Apps, the **Save as default** chip on an image card calls this tool.

**Permission:** `workflows:execute`. **Credits:** free.

| Parameter | Type | Notes |
| --- | --- | --- |
| `model` | string or null | Your default model. `null` clears it and goes back to the catalog default. |
| `aspect_ratio` | string or null | Your default aspect ratio. |
| `resolution` | string or null | Your default resolution. |
| `quality` | string or null | Your default quality. |

**Returns:** a confirmation.

## Frequently asked questions

### Which model does generate_image use by default?

Nano Banana 2. Pass model with another id from list_models to change it, for example nano-banana-pro for readable text or gpt-image-2-5-flare for fast iterations. An unknown id falls back to the default without an error.

### How do I keep the same person in several images?

Pass the person's pictures in reference_image_urls, up to 14 URLs or Nodaro ids, and the reply confirms how many were attached. For a saved character, pass the approved portrait that get_character returns.

### How do I remove a background or upscale an image through MCP?

Use edit_image. Set model to recraft-remove-bg for a transparent PNG, or to recraft-upscale or topaz-image-upscale to upscale. None of them needs a prompt.

### Can an assistant put a logo or text on an image without AI?

Yes. image_overlay places images, text, QR codes and shapes on a base image, pixel-exactly and without a model, for 10 credits. suggest_overlay_placement can first propose where a logo should go.

### How much does an image generation cost through MCP?

The same as in the editor. The price depends on the model and its resolution or quality; list_models and each model page list the exact credits.