| 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
- For each local input image, upload to Fal storage to get a public URL (
scripts/upload.sh).
- POST to
https://fal.run/fal-ai/nano-banana/edit with {prompt, image_urls, ...}.
- Download each returned image URL into the output dir as
image_001.png, image_002.png, ...
- 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.
