Image edits

Given an original image and a prompt, the model produces a new image by editing only the areas indicated by a transparent mask. Use this to replace backgrounds, add objects, or touch up specific regions while preserving everything else.

POST/v1/images/edits

Send a multipart/form-data request with the original image, an optional mask, and a text prompt. The mask must be a PNG with a transparent area indicating where the edit should be applied. The model used is dall-e-2.

Required parameters

FieldTypeDescription
imagefileThe original image to edit. Must be a square PNG, less than 4 MB.
promptstringA text description of the desired edit. Max 1000 characters.
maskfileA square PNG with a transparent area where the edit should be applied. Must match the dimensions of the image.
nintegerNumber of images to generate. Defaults to 1. Range 1–10.

Example request

curl https://api.getnimbus.net/v1/images/edits \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -F image="@original.png" \
  -F mask="@mask.png" \
  -F prompt="A futuristic city skyline at sunset" \
  -F n=1

Response

{
  "created": 1716500000,
  "data": [
    {
      "url": "https://cdn.getnimbus.net/img/abc123.png",
      "revised_prompt": "A futuristic city skyline..."
    }
  ]
}

Notes

  • •The mask must be a PNG with an alpha channel. Fully transparent pixels indicate the area to edit; opaque pixels are preserved.
  • •Both the image and mask must be square and the same dimensions. Supported sizes: 256×256, 512×512, or 1024×1024.
  • •The dall-e-2 model is used for all image edit requests. Higher resolution inputs produce higher resolution outputs.
  • •Rate limits apply per API key. See the rate limits page for details.
← Image variationsImage generation →