> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developer.ideogram.ai/v2/llms.txt
> - v1: https://developer.ideogram.ai/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.ideogram.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server.

> Edit one region of an image with the Ideogram API: choose Precise Edit or Inpaint, build a black-and-white mask, send it, and check the area outside the mask.

To change one part of an image, send the image with a mask. Mask colors differ between endpoints, so check this table before you build one:

| Endpoint                                                                                                                                                                                                                    | The area to change                     | The area to keep      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | --------------------- |
| [Precise Edit with Ideogram 4.5](/v2/api-reference/images/precise-edit/ideogram-4-5), and the `mask` on [Generate with Ideogram 4.5](/v2/api-reference/images/generate/ideogram-4-5)                                        | Black                                  | White                 |
| [Inpaint with Ideogram 3.0](/v2/api-reference/images/inpaint/ideogram-3), and its character and custom model versions                                                                                                       | Black                                  | White                 |
| [Remove Objects](/v2/api-reference/images/remove-object/ideogram-1)                                                                                                                                                         | White                                  | Black                 |
| The `mask` on [GPT Image 2](/v2/api-reference/images/generate/gpt-image-2), [2.5 Flare](/v2/api-reference/images/generate/gpt-image-2-5-flare) and [2.5 Sunburst](/v2/api-reference/images/generate/gpt-image-2-5-sunburst) | White                                  | Black                 |
| [Colorways](/v2/api-reference/tools/colorways) and [Material Swap](/v2/api-reference/tools/material-swap)                                                                                                                   | White, or opaque in an alpha-only mask | Black, or transparent |

This page covers Precise Edit and Inpaint.

## Choose an endpoint

|                  | Precise Edit, Ideogram 4.5                                          | Inpaint, Ideogram 3.0                        |
| ---------------- | ------------------------------------------------------------------- | -------------------------------------------- |
| Mask             | Optional. Without one, the edit follows the prompt across the image | Required                                     |
| Mask colors      | Black = edit, white = keep                                          | Black = repaint, white = keep                |
| Reference images | Up to 4, or 3 with a mask                                           | None; up to 10 `style_reference_images`      |
| Image size       | Up to 50 MB; the result keeps the image's width and height          | Up to 25 MB                                  |
| Use it for       | Changing an object, a material, a color or text in place            | Repainting a region in an Ideogram 3.0 style |

## Build the mask

* Make the mask the same width and height as the image.
* Paint the area to change black and everything else white. Precise Edit rounds in-between values to the nearer of the two and needs both colors in the mask.
* Save it as JPEG, PNG or WebP.

This Pillow example marks a rectangle for editing:

```python
from PIL import Image, ImageDraw

image = Image.open("room.png")
mask = Image.new("L", image.size, 255)  # white: keep
ImageDraw.Draw(mask).rectangle((420, 300, 980, 760), fill=0)  # black: edit
mask.save("mask.png")
```

## Send the request

Masks go in a `multipart/form-data` request:

```bash
curl -X POST https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-5 \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -F image=@room.png \
  -F mask=@mask.png \
  -F prompt="Change the sofa to deep green velvet."
```

Name only what should change in the prompt. By default (`context_window: auto`), Precise Edit fits its working region around the masked area.

The same request in Python, saving the result as `edited.png`:

```python
import os

import requests

with open("room.png", "rb") as image, open("mask.png", "rb") as mask:
  response = requests.post(
    "https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-5",
    headers={"Api-Key": os.environ["IDEOGRAM_API_KEY"]},
    files={"image": image, "mask": mask},
    data={"prompt": "Change the sofa to deep green velvet."},
    timeout=300,
  )
response.raise_for_status()
result = response.json()["data"][0]
with open("edited.png", "wb") as file:
  file.write(requests.get(result["url"], timeout=60).content)
```

## Check the area outside the mask

Pixels outside the mask can still change slightly. Compare that area with the original before you use the result. If those pixels must stay exactly as they were, paste them back from the original:

```python
from PIL import Image

original = Image.open("room.png").convert("RGB")
edited = Image.open("edited.png").convert("RGB")
mask = Image.open("mask.png").convert("L")

# Inpaint snaps its output to the nearest supported resolution, so match sizes first.
if edited.size != original.size:
  edited = edited.resize(original.size, Image.LANCZOS)

# Where the mask is white, keep the original; where it is black, keep the edit.
Image.composite(original, edited, mask).save("final.png")
```

Precise Edit returns the image at its own width and height, so its result composites as it is. Inpaint returns the nearest supported Ideogram 3.0 resolution, which the example resizes back to the original first.

## In the app

The Ideogram app has the same masks in its Precise Edit app. See [Masks and Inpainting](https://docs.ideogram.ai/edit/masks-and-inpainting).