Edit an image

Returns 202 straight away with the job and what it charged. Poll GET /v2/jobs/{id} for the result; a job that fails is refunded. An edit is $0.099 and an erase $0.099, whichever engine made the image.

Choosing the area

• A region: a box or a polygon in fractions of the image, drawn at the image’s own size, so it means the same on any resolution.
• A mask: a black-and-white PNG the size of the image, white where to change, sent like the image (a file, a link or base64).
• Neither: an edit changes the whole image. An erase always needs an area.

Headers

AuthorizationstringRequired

Bearer mk_live_…: your API key. See Authentication.

Content-TypestringRequired

application/json, or multipart/form-data to send a file.

Idempotency-Keystring

Your own key, 1 to 255 visible ASCII characters. A retry with the same key and request within 24 hours returns the first answer instead of running again.

Body

kindstringDefault edit

edit changes what the prompt names. erase removes what the area covers and fills in the background.editerase

promptstring

What to change, in plain words. Required for an edit; an erase takes none.

imagestring

The JPEG, PNG or WebP to work on, up to 15 MB: a public https:// link we fetch, a data:image/…;base64, URI, or bare base64. With multipart form data, attach the file itself (-F [email protected]). Send one of image or job_id.

job_idstring

A finished job of yours: work on its output without downloading it first.

enginestringDefault v4.6-ultra

The engine whose edit runs. An erase takes none.

modestringDefault exterior

What the image shows. An erase takes none.exteriorinteriormasterplanplanlandscapeproducttext-to-render

referencesstring | object[]

Images whose style, materials, mood or geometry to follow, up to 15. Each is just the image (a link or base64, or with multipart a references file part, repeated), or an object, { image | job_id, mode }, that also sets its mode. How many an engine takes is capabilities.max_references in GET /v2/engines.

Fields of each item (3)

imagestring

The reference image: a public https:// link we fetch, a data:image/…;base64, URI, or bare base64. With multipart form data, attach the file itself. Send one of image or job_id.

job_idstring

The reference image, as a finished job of yours.

modestringDefault style

What to take from it: its style, a material, the atmosphere, the color or the geometry. auto lets the engine decide.autostylematerialatmospherecolorgeometry

regionobject

The area to change, as a box or a polygon, in 0–1 fractions of the image from its top-left corner. Leave it out to edit the whole image.

Fields (2)

boxobject

A rectangle.

Fields (4)

xnumberRequired

Its left edge, 0–1 of the image’s width.

ynumberRequired

Its top edge, 0–1 of the image’s height.

widthnumberRequired

Its width, 0–1 of the image’s width.

heightnumberRequired

Its height, 0–1 of the image’s height.

polygonnumber[][]

Any outline, as [[x, y], …] points in the same 0–1 fractions.

maskstring

The area as a mask: a PNG the size of the image, white where to change, black where to keep. a public https:// link we fetch, a data:image/…;base64, URI, or bare base64. With multipart form data, attach the file itself. Send region or mask, not both.

webhook_urlstring

A public https:// URL to send this job’s settle event to, signed like every webhook, on top of your account’s endpoints.

Response

On success (202): Started. Poll GET /v2/jobs/{id} for the result. The JSON is { "success": true, "data": … }, and inside data:

idstringRequired

The job. Read it at GET /v2/jobs/{id}.

statusstringRequired

The job’s status when it was accepted, usually queued.queuedprocessingsucceededfailedcanceled

charged_usdnumberRequired

What this call charged, in US dollars. A job that fails is refunded.

replayedbooleanRequired

True when this is the stored answer to an earlier identical request with the same Idempotency-Key: nothing ran or was charged again. See Idempotency.

notesstring[]Required

What was accepted but not applied, in plain words: a setting that does not fit the engine, a seed it does not take. Empty when everything applied.

Status codes

202

Started. Poll GET /v2/jobs/{id} for the result.

401

The API key is missing, malformed, unknown or revoked.

402

The balance does not cover this call.

409

The Idempotency-Key was reused for a different request, or is still in progress.

429

A limit was reached: requests per minute, or a daily or concurrency limit.

Other

Any other error, in the same envelope.

Every error answers { "success": false, "error": { "code", "message" } }. What each code means, and what to do, is on Errors.