Skip to main content
POST
Edit an image with a prompt (Magic Edit)
Submit a source image and a prompt describing the edit. The call returns 202 Accepted with a job id; poll GET /images/edits/{id} for the result. The image object takes exactly one of image_id, url, or base64 + mime_type.

Example: masked edit from a URL

Provide the source by url, add an inpaint mask (its presence selects PRO mode), and reuse a style model. The mask is a base64-encoded image marking the region to edit.
Send exactly one source mode in image. Omit mask for a text-only (SIMPLE) edit; a mask works only on nano_banana_pro and gemini. resolution (1K, 2K, 4K) applies to nano_banana_pro, nano_banana_2, and nano_banana_2_1; omit it for gemini and kontext. Trained models and color_palette_id work only with nano_banana_pro — another named engine returns 422. num_images (1–4) defaults to 1. See Engines and credits.

Response

The 202 body echoes the effective engine and resolution, so you can see what the edit runs at and what it costs:
202 Accepted
resolution is null on gemini and kontext. estimated_credits is the amount deducted: 5 / 10 / 20 per output at 1K / 2K / 4K on the Nano Banana engines, a fixed 5 per output on gemini and kontext, × num_images.

Authorizations

Authorization
string
header
required

Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).

Body

application/json

POST /images/edits body (ADR §8, §10) — Magic Edit.

Supply a prompt and a source image; optionally a mask (auto-selects PRO mode), trained models you own (including your own private models) or shared within your organization (style_id/object_ids/person_ids/ setting_ids, color_palette_id — only on nano_banana_pro; any other named engine is a 422, never a silent switch), an engine (a public-safe alias of the internal edit model) and a resolution (Nano Banana engines only). The source aspect ratio is kept. num_images defaults to 1.

image
PublicImageEditSource · object
required

The source image: exactly one of image_id, url, or base64+mime_type.

prompt
string
required

Text prompt describing the edit. Runs the same validation as the app (rejects empty / malformed / policy-violating prompts with a 422).

Minimum string length: 1
Example:

"Replace the sky with a dramatic sunset"

mask
PublicImageEditMask · object | null

Optional inpaint mask. When present, the edit runs in PRO (mask-based) mode — supported only by the nano_banana_pro, gemini engines; any other engine returns 422.

engine
string | null

Edit engine — one of nano_banana_pro (Nano Banana Pro, default), nano_banana_2 (Nano Banana 2), nano_banana_2_1 (Nano Banana 2.1), gemini (Nano Banana), kontext (Flux Kontext). Omit to use the default. Unknown engines return 422. Trained models and a color palette work only with nano_banana_pro (also used when engine is omitted); naming any other engine together with them returns 422 — the engine is never switched silently.

Example:

"nano_banana_pro"

style_id

A style model NAME or its UUID id (from list_models), resolved within your visible set — a model you own (including your own private models) or a non-private one shared with your organization. A name matching more than one visible model is rejected — pass the id. Only with nano_banana_pro (another named engine is a 422).

object_ids
(string<uuid> | string)[]

object models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id.

person_ids
(string<uuid> | string)[]

person models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id.

setting_ids
(string<uuid> | string)[]

setting models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id. Maps to internal scenes.

color_palette_id

A color palette NAME or its UUID id, resolved within your visible set — a palette you created (including private ones) or a non-private palette shared with your organization. A name matching more than one visible palette is rejected — pass the id. Only with nano_banana_pro (another named engine is a 422).

resolution
string | null

Output resolution — 1K, 2K, or 4K on nano_banana_pro, nano_banana_2, nano_banana_2_1 (credits scale 1K:1x, 2K:2x, 4K:4x; omitted = 1K). gemini, kontext have a fixed resolution — omit it there (a value returns 422). The response echoes the effective resolution.

Example:

"4K"

num_images
integer
default:1

Number of edited images to generate (1-4). Defaults to 1; each output is billed.

Required range: 1 <= x <= 4
Example:

1

output_format
enum<string>
default:png

Encoding of the returned images. v1 supports png only.

Available options:
png
Example:

"png"

webhook_url
string | null

Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).

Example:

"https://example.com/webhooks/samsa"

Response

Successful Response

202 body for POST /images/edits (ADR §7.1).

id
string<uuid>
required

The image-edit job id — poll GET /images/edits/{id}.

status
enum<string>
required

Initial status: always pending at submit.

Available options:
pending,
processing,
completed,
failed,
cancelled
Example:

"pending"

estimated_credits
integer
required

Credits this job is expected to cost — and the amount deducted: 5 x num_images x resolution multiplier on nano_banana_pro, nano_banana_2, nano_banana_2_1 (1K:1x, 2K:2x, 4K:4x), 5 x num_images on gemini, kontext.

Example:

20

engine
string
required

The engine this edit runs on (the requested engine, or nano_banana_pro when omitted). Never switched silently.

Example:

"nano_banana_pro"

resolution
string | null
required

The output resolution this edit runs at (the requested resolution, or the engine default 1K); null for the fixed-resolution engines (gemini, kontext).

Example:

"4K"