Images

Edit a masked region of an image (async)

Regenerate the masked area of an image already in your library from a prompt, using GPT Image 2.5 Sunburst. Everything outside the masked area is preserved. Returns a job_id; poll GET /v1/jobs/{id} until completed. There is no region-edit status route.

Supply exactly one mask, never both: mask_file_uuid (a PNG already in your library) or mask (inline base64 PNG bytes). Neither is a 400, and both is a 400. The mask must match the source image's pixel dimensions exactly and must have an alpha channel: fully transparent pixels (alpha 0) mark the area to change, opaque pixels (alpha 255) mark the area to keep. The mask file must be smaller than 4194304 bytes (4 MB); an inline mask whose base64 payload is longer than 5592408 characters is refused before it is decoded. The inline form exists because files/upload is not exposed as an MCP tool, so inline is the only way an agent can supply a freshly drawn mask.

Every mask check runs before any credit is reserved: a refused mask costs nothing. A request that passes is charged the current image_region_edit price, reported as estimated_credits in the 202.

post/v1/images/region-edit

Request

  • Base URL: https://contentmaschine.ai/api
  • URL: https://contentmaschine.ai/api/v1/images/region-edit
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://contentmaschine.ai/api/oauth/authorize, token URL https://contentmaschine.ai/api/oauth/token)

Request body

source_file_uuidstring uuid required

UUID of the image in your library to edit.

promptstring required

What to put inside the masked area.

mask_file_uuidstring uuid

UUID of a mask PNG already in your library. Send this OR mask, never both. Same pixel dimensions as the source, with an alpha channel: transparent = change, opaque = keep.

maskstring

The mask PNG inline, as unwrapped base64 (an optional "data:image/png;base64," prefix is accepted). Send this OR mask_file_uuid, never both. Smaller than 4194304 bytes decoded; a payload longer than 5592408 base64 characters (prefix excluded) is refused before decoding. Same pixel dimensions as the source, with an alpha channel: transparent = change, opaque = keep.

Response

Region edit job queued

successboolean
timestampstring date-time

Example response

{
  "success": true,
  "data": {
    "status": "pending"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.