Skip to main content
Magic Edit takes a source image and a prompt and returns an edited image. Supply the source three ways — an 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

Pass engine 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, or 4K on the three Nano Banana engines; omitted means 1K. gemini and kontext have a fixed resolution — a resolution value there returns 422.
  • Mask. A mask runs the edit in PRO (mask-based) mode, supported only by nano_banana_pro and gemini.
  • Trained models and palettes. style_id, object_ids, person_ids, setting_ids, and color_palette_id work only with nano_banana_pro (named or omitted engine). Naming any other engine together with one of them returns 422 — the engine is never switched.
The 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.