create-image-nano-banana-2-fal

name	create-image-nano-banana-2-fal
description	Generate a single still image with Nano Banana 2 (Google Gemini 2.5 Flash Image, multi-image edit mode) via fal.ai. Multi-reference editing — the default atom for AI avatar portraits, product flatlay/endcard backgrounds, and any composite scene that combines 2-4 reference images with a text prompt. Used as the upstream still generator for `bytedance/seedance-2.0/reference-to-video`.

create-image-nano-banana-2-fal

Purpose

The FAL-native call for Nano Banana 2 edit (fal-ai/nano-banana-2/edit). NB2 is Google's Gemini 2.5 Flash Image model in multi-reference edit mode — given a prompt + 1–N reference images, it produces a single composite still that preserves identity / product / setting elements from the refs while honoring the text directive.

Use this atom when:

• Generating an AI avatar portrait that will be passed downstream to Seedance 2.0 reference-to-video as the identity anchor
• Generating a product flatlay or hyperframe background plate from real product PNGs
• Compositing 2-4 references (avatar + product + setting + style) into a single still
• Any still where multi-image edit beats text-only generation

For text-only image gen with no references, use create-image-nano-banana-fal (NB v1, cheaper). For complex camera/lens-specific product photoshoots, use create-product-images-higgsfield-product-photoshoot.

Inputs

Required:

• --prompt — text directive. No brand text in the prompt — NB2 still garbles wordmarks; overlay typography in post via HTML.
• --output — local PNG destination.
• --ref-image — at least one reference image (repeatable). The atom passes these as image_urls after uploading.

Optional:

• --aspect-ratio — 9:16 (default for vertical ads), 16:9, 1:1, 4:3, 3:4.
• --num-images — default 1. Bump to 2-4 for variants in a single call (e.g. portrait variations).
• --with-logs — stream FAL queue updates to stdout.

Credentials:

• FAL_API_KEY (or FAL_KEY) in .env.

Workflow

python3 skills/atoms/image-generation/create-image-nano-banana-2-fal/scripts/generate.py \
  --prompt "..." \
  --output /path/to/portrait-hero.png \
  --ref-image /path/to/face-ref.png \
  --ref-image /path/to/product.png \
  --aspect-ratio 9:16

The script:

1. Loads FAL key via the shared fal_helpers.load_fal_key().
2. Uploads each --ref-image to FAL storage (returns https://v3.fal.media/... URLs).
3. Calls fal_client.subscribe("fal-ai/nano-banana-2/edit", {prompt, image_urls, aspect_ratio, num_images}).
4. Downloads the result PNG(s) to --output (and <output>.varN.png for >1).
5. Writes <output>.meta.json with prompt, refs, image URL, seed, cost estimate.

Output

• <output> — PNG (> 1 KB; smaller = error payload).
• <output>.meta.json — request + result metadata + cost.
• For --num-images N: <output> (variant 1) plus <stem>.var2.png, <stem>.var3.png, ...

Pricing

• ~$0.08 per image call (2026-05 estimate; verify against current FAL pricing).
• Cheaper than Higgsfield's nano_banana_2 for pure FAL pipelines.

Quality Checks

• Output file exists and is > 1 KB.
• Aspect ratio matches the request (verify via PIL or ffprobe).
• meta.json includes gateway: "fal", model: "fal-ai/nano-banana-2/edit".
• No brand text rendered in image (it will be garbled — overlay in post).
• Identity / product reference preserved (visual check against ref images).

Failure Modes

Symptom	Likely cause	Fix
401 Unauthorized	Bad / missing FAL_API_KEY	Verify env var.
429 Too Many Requests	Account RPS limit	Drop concurrency to 2-3.
Garbled brand text in image	Asked NB2 to render wordmark	Strip brand text from prompt; overlay via HTML hyperframe in post.
Heavy freckles / blotchy skin	Block B language too aggressive	Use v8 soft-skin language ("tiny natural imperfections, subtle peach fuzz, faint fine lines"). Avoid "freckles prominent", "real-person imperfections".
Identity drift on multi-image input	Refs conflict (e.g. two faces)	Pass one identity ref + only object refs; don't mix two creators in one call.
Output drifts from style anchor	Reference order matters — first ref dominates	Put the identity / style anchor FIRST in --ref-image flags.
Geometry change requested but ignored	NB2 anchors on source shape	Geometry changes (e.g. bottle → tube) often fail. Regenerate from scratch with text-only or a new ref.

Notes

• Reference order matters. First --ref-image becomes @Image1 in the model's internal addressing; subsequent refs are @Image2, @Image3, etc. Prompts that say "use @Image1 as the face" depend on this order.
• Multi-image budget. FAL caps image_urls per call. Stay ≤ 4 refs for reliable output; degrade quality observed above 5.
• No video refs. This endpoint is image→image only. Video continuity belongs in Seedance 2.0 reference-to-video — and even there, never pass AI-generated video as video_urls (content_policy_violation).

References

• FAL model page: https://fal.ai/models/fal-ai/nano-banana-2/edit
• Sibling FAL atom (NB v1, text-led): skills/atoms/image-generation/create-image-nano-banana-fal
• Reference run using this pattern: beauty-by-earth/video-01-three-product-grwm/working/fire_v8_pilot.py
• Shared helpers: skills/atoms/_shared/fal_helpers.py