Skip to navigation

Edit One Region with a 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:

EndpointThe area to changeThe area to keep
Precise Edit with Ideogram 4.5, and the mask on Generate with Ideogram 4.5BlackWhite
Inpaint with Ideogram 3.0, and its character and custom model versionsBlackWhite
Remove ObjectsWhiteBlack
The mask on GPT Image 2, 2.5 Flare and 2.5 SunburstWhiteBlack
Colorways and Material SwapWhite, or opaque in an alpha-only maskBlack, or transparent

This page covers Precise Edit and Inpaint.

Choose an endpoint

Precise Edit, Ideogram 4.5Inpaint, Ideogram 3.0
MaskOptional. Without one, the edit follows the prompt across the imageRequired
Mask colorsBlack = edit, white = keepBlack = repaint, white = keep
Reference imagesUp to 4, or 3 with a maskNone; up to 10 style_reference_images
Image sizeUp to 50 MB; the result keeps the image’s width and heightUp to 25 MB
Use it forChanging an object, a material, a color or text in placeRepainting 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:

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:

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:

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:

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.