image_id already in your organization’s context (for
example a local file uploaded first), an
https url, or inline base64 + mime_type. Add a mask to run in PRO
(mask-based inpaint) mode, and reuse your trained style/object/person/
setting models and color palettes for on-brand results.
Asynchronous pattern
Like generation, editing is asynchronous:POST /images/edits returns
202 Accepted with a job id; poll
GET /images/edits/{id} until completed, then
read the edited images (presigned URLs valid 24 hours). A webhook_url gives
you a push callback instead — see Webhooks.
Engines and credits
Passengine to pick the edit model; omit it to use the default,
nano_banana_pro. The source aspect ratio is always kept.
Every rule below returns
422 (with param set to the field) before any credits
are charged:
- Unknown engine. The message lists the five valid keys.
- Resolution.
1K,2K, or4Kon the three Nano Banana engines; omitted means1K.geminiandkontexthave a fixed resolution — aresolutionvalue there returns422. - Mask. A
maskruns the edit in PRO (mask-based) mode, supported only bynano_banana_proandgemini. - Trained models and palettes.
style_id,object_ids,person_ids,setting_ids, andcolor_palette_idwork only withnano_banana_pro(named or omittedengine). Naming any other engine together with one of them returns422— the engine is never switched.
202 response echoes the effective engine (the one you named, or
nano_banana_pro) and resolution (1K when omitted on a Nano Banana engine;
null on gemini and kontext). num_images (1–4, default 1) multiplies
the cost, and estimated_credits is the amount deducted. Costs draw from your
organization’s pool; an exhausted pool returns 402. See
Pricing.