Image Edits (Image-to-Image, Masks, and Multiple References)

/v1/images/edits accepts:

• multipart/form-data for local source images, multiple references, and mask files.
• application/json for publicly downloadable HTTPS images and masks.

Endpoint

POST https://api.ezmodel.cloud/v1/images/edits
Authorization: Bearer YOUR_API_KEY

Multipart fields

Field	Type	Required	Description
model	string	Yes	Use gpt-image-2
prompt	string	Yes	Requested edit, up to 32,000 characters
image	file	For one image	Single source image
image[]	file[]	For multiple images	Repeat this field, up to 16 images
mask	file	No	Alpha-channel PNG matching the first image's dimensions
n	integer	No	Number of outputs from 1 to 10; default 1
size	string	No	auto, a standard size, or a valid custom size
quality	string	No	auto, low, medium, or high
background	string	No	auto or opaque
output_format	string	No	png or jpeg
output_compression	integer	No	JPEG compression quality from 0 to 100
user	string	No	End-user identifier

Input images may be PNG, WebP, or JPEG and must be smaller than 50 MB each.

Single-image edit

curl https://api.ezmodel.cloud/v1/images/edits \
  -H "Authorization: Bearer $EZMODEL_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=Change the sky to sunset while preserving the building structure' \
  -F 'image=@original.png' \
  -F 'quality=low' \
  -F 'n=1' \
  -F 'size=1024x1024'

Multiple references

Image order is meaningful. State the role of each image in the prompt.

curl https://api.ezmodel.cloud/v1/images/edits \
  -H "Authorization: Bearer $EZMODEL_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=Keep the subject and composition from image one; apply the blue color style from image two' \
  -F 'image[]=@subject.png' \
  -F 'image[]=@style.png' \
  -F 'quality=low' \
  -F 'n=1'

Masked edit

The mask must be an alpha-channel PNG matching the first source image's dimensions. Fully transparent areas are edited; opaque areas are preserved. The mask must be smaller than 4 MB.

curl https://api.ezmodel.cloud/v1/images/edits \
  -H "Authorization: Bearer $EZMODEL_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=Add a floor lamp only in the transparent mask area; preserve everything else' \
  -F 'image=@room.png' \
  -F 'mask=@mask.png' \
  -F 'quality=low'

JSON with HTTPS references

images is an array of objects containing image_url. mask is an object containing image_url. Do not send the URLs as bare strings.

curl https://api.ezmodel.cloud/v1/images/edits \
  -H "Authorization: Bearer $EZMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Make the product blue, editing only the transparent mask area while preserving the label",
    "images": [
      {
        "image_url": "https://example.com/assets/product.png"
      }
    ],
    "mask": {
      "image_url": "https://example.com/assets/mask.png"
    },
    "quality": "low",
    "n": 1
  }'

Omit mask when it is not needed. Every URL must remain publicly downloadable until processing completes. A remote mask must also be an alpha-channel PNG matching the first reference image's dimensions.

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.ezmodel.cloud/v1",
)

with open("original.png", "rb") as image:
    response = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="Change the sky to sunset while preserving the building structure",
        quality="low",
        n=1,
    )

image_base64 = response.data[0].b64_json
print(image_base64[:80])

Edit responses use the same structure as generation responses. usage.input_tokens_details.image_tokens reports input image tokens.