Image Edits

Edit images using text prompts, masks, and inpainting.

Edit images by providing a source image, an optional mask, and a text prompt describing the desired changes. This is commonly known as inpainting.

POST /v1/images/edits

Authentication

AuthorizationBearerrequired

API key as bearer token in the Authorization header. Create keys at Manage API Keys.

Headers

Content-Typestringrequired

Must be multipart/form-data.

Body

imageFilerequired

The image to edit. Must be a valid PNG file, less than 4MB, and square. Transparent areas will be used as the mask if no mask is provided.

promptstringrequired

Text description of the desired edit or what should fill the masked area.

modelstringrequired

Image model id from GET /v1/models. Example: dall-e-2, gpt-image-1.

maskFileoptional

An additional image whose fully transparent areas indicate where the original image should be edited. Must be a valid PNG file, less than 4MB, and the same dimensions as image.

nintegeroptionalDefault 1

Number of images to generate. Range: 1-10.

sizestringoptionalDefault 1024x1024

Output dimensions.

Allowed values:256x256512x5121024x1024
response_formatstringoptionalDefault url

url returns a temporary URL (valid ~1 hour), b64_json returns inline base64 data.

Allowed values:urlb64_json
userstringoptional

End-user identifier for abuse tracking.

Mask behavior

The mask indicates where edits should be applied. Transparent areas in the mask are where the model will generate new content based on your prompt. If no mask is provided, transparent areas in the source image are used.

Response

createdintegeroptional

Unix timestamp (seconds) when the images were generated.

dataImage[]optional

Array of edited images. Each contains either url or b64_json depending on response_format.

Use cases

  • Inpainting: Fill in or replace specific parts of an image
  • Object removal: Mask an object and prompt for background fill
  • Object replacement: Mask an area and describe what should replace it
  • Style transfer: Apply changes to masked regions