Inpainting

Mark an area with a mask and repaint only that area; everything else stays as it was.

Not writing code? See Generate images in your own tools.

POST/v1/images/editsShared parameters

Before you start

You need	Details
API key	Create one in the OfoxAI console and replace `YOUR_OFOX_API_KEY` in the code
Environment	cURL needs `jq` to decode the image; Python needs `pip install openai`, plus `pip install pillow` to generate the mask; Node.js 18 or later, no dependencies
Images	Put an `input.png` and a `mask.png` of the same size in the current directory. No mask yet? Step 1 below shows how to make one
Timeout	Set your client timeout to 600 seconds. High quality, large sizes or editing can take several minutes

Values used in the code

API URLhttps://api.ofox.io/v1

Model IDopenai/gpt-image-2.5-flare

API keyReplace YOUR_OFOX_API_KEY in the code with your key

Python depspip install openai pillowpillow is used to make the mask

Mask requirements

Original

Masktransparent center, opaque elsewhere

→

Resultonly the transparent area is repainted

Illustration, not an actual generated result

A PNG with an alpha channel. JPEG and opaque PNG do not work.
Exactly the same size as the original image.
Transparent pixels are repainted; opaque pixels keep the original.
Only works on the edit endpoint. Sent to text to image, it is ignored.

Steps

Make a mask

Skip this step if you already have one.

This snippet reads input.png from the current directory, makes the middle 40% square transparent, and saves it as mask.png.

make_mask.py


from PIL import Image, ImageDraw
 
src = Image.open("input.png")
mask = Image.new("RGBA", src.size, (0, 0, 0, 255))          # fully opaque = keep everything
w, h = src.size
ImageDraw.Draw(mask).rectangle(                              # transparent area = what gets repainted
    (int(w * 0.3), int(h * 0.3), int(w * 0.7), int(h * 0.7)), fill=(0, 0, 0, 0)
)
mask.save("mask.png")

Send the request

Every sample below was run verbatim. The result is saved as output.png in the current directory.

cURL

Terminal


# mask.png: same size as input.png, with an alpha channel; transparent area = what gets repainted
curl -s https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "prompt=An orange cat sitting in the center, background and everything else unchanged" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

Writing the prompt

Describe the whole image as it should look afterwards, not just what to add.

	Prompt	Measured result
✅	An orange cat sitting in the center, background and everything else unchanged	A cat in the middle; the rest unchanged
❌	Draw a cat in the transparent area	The model treated “transparent” as content and drew a checkerboard background

Measured result

Outside the mask the image barely changes: the mean pixel difference from the original is under 2/255.

For comparison, editing the same image without a mask changed the same area by 120/255.

Troubleshooting

Symptom	Cause	Fix
`Invalid image file or mode` error	The mask is not a PNG with an alpha channel	Regenerate it with the code in step 1 above
The whole image changed	The mask had no effect: it was sent to the text-to-image endpoint, or the mask is fully opaque	Check that you are calling `/v1/images/edits` and that the mask has a transparent area
A checkerboard background appeared	The prompt mentioned “the transparent area”	Describe the whole image, as in Writing the prompt

For other errors, see the full error table.

Official docs

OpenAI’s docs describe behavior when you call OpenAI directly. When you call through OfoxAI, the measured results in these pages take precedence. For example, you don’t need to pin a provider for editing.