edit-image-nano-banana

name	edit-image-nano-banana
description	edit images via fal-hosted nano banana / gemini 2.5 flash image — fast prompt-driven edits, multi-subject consistency, photorealism.

edit-image-nano-banana

Purpose

Default editor — start here for any prompt-driven image edit. Strongest at photorealism, multi-subject consistency, full-scene restages, subject swaps, and fast iteration. Switch to edit-image-gpt-image only when typography / text rendering is the whole point of the edit (logos, wordmarks, signage).

Backed by Fal model fal-ai/nano-banana/edit.

When to use this vs edit-image-gpt-image

Validated against the skill-tests/edit-image-tests/ bench (3 edits × 2 models):

edit type	use
Restage / scene swap (bike → living room)	nano-banana — characterful, fast, preserves subject geometry
Subject swap (woman → man, same pose)	nano-banana — clean swap, room/lighting/frame held
Logo / wordmark / typography edit	gpt-image with --quality high — sharpest letterforms
Incidental text inside a non-text edit	Either — both can mangle small text in the source; flag for review
Transparent-background cutout	gpt-image with --background transparent --format png

Inputs

• prompt (string) — natural-language edit instruction.
• image_paths (one or more) — local image paths or public HTTPS URLs.
• Output directory.
• Optional: aspect_ratio, num_images, output_format, seed.
• FAL_KEY in env.

Workflow

1. For each local input image, upload to Fal storage to get a public URL (scripts/upload.sh).
2. POST to https://fal.run/fal-ai/nano-banana/edit with {prompt, image_urls, ...}.
3. Download each returned image URL into the output dir as image_001.png, image_002.png, ...
4. Write request.json, response.json, manifest.json.

Use scripts/edit.sh for the full flow.

Key parameters

• prompt (required).
• image_urls (required, ≥1).
• aspect_ratio — auto (default), 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16.
• num_images — 1–4, default 1.
• output_format — png (default), jpeg, webp.
• safety_tolerance — 1–6, default 4.
• seed — int, optional.

No mask field — this is a prompt-only edit model. For region-locked edits, prompt nano-banana to "keep everything else unchanged" or use Higgsfield Soul via the mcp__higgsfield__* MCP tools for identity-preserving inpaint.

Output

• image_NNN.<ext> — edited image(s).
• request.json, response.json — API payloads.
• manifest.json — status, model, prompt, inputs[], outputs[], seed, warnings.

Quality checks

• Output file(s) exist and decode (file image_001.png reports valid image).
• Dimensions match requested aspect ratio (or input ratio when auto).
• No watermarks, garbled text, or extra fingers — flag for review if present.
• Multi-subject consistency preserved when input has multiple people/products.

Failure modes

• Missing FAL_KEY.
• 422 — invalid image_urls (must be public HTTPS or data: URI; local paths must be uploaded first).
• 429 / quota — back off and retry.
• Long edge > ~2048px — downscale before submitting.
• Text-heavy edits look soft — switch to edit-image-gpt-image (run with --quality high for wordmarks).
• Need identity-preserving inpaint — use Higgsfield Soul via mcp__higgsfield__* MCP tools.