fal-ai-image

Generate images via fal.ai nano-banana-pro (Gemini 3 Pro Image). Best for: infographics, text rendering, complex compositions.

STOP — Read Before Acting

• •DO NOT use Pillow, ImageMagick, or any post-processing for text/logo overlay — this model renders text natively, including Cyrillic and CJK
• •DO NOT use Generate mode when user provides reference images — use Edit mode
• •DO NOT launch general-purpose subagents — use Task with subagent_type: "Bash" and model: "haiku"
• •DO NOT skip uploading local files — run upload.sh first to get URLs for edit.sh
• •DO NOT guess script parameters — check the tables below

Quick Start Decision

User gave reference images?  → Edit mode  (upload.sh → edit.sh)
User wants text-only gen?    → Generate mode (generate.sh)
Multiple images needed?      → Parallel Bash/haiku subagents

Model Capabilities

• •Excellent text rendering (Latin, Cyrillic, CJK) — no post-processing needed
• •Composes logos, product photos, and text into banners in a single pass
• •Understands layout instructions ("left side text, right side product photo")
• •Handles complex infographics, charts, and diagrams
• •Edit mode blends reference images naturally with prompt guidance

Compatibility

Scripts are POSIX sh compatible — work in cloud sandboxes (/bin/sh) and locally (bash). No bashisms: [[ ]], ${BASH_SOURCE}, source etc. are NOT used.

Config

Requires FAL_KEY in config/.env or environment. Get key: https://fal.ai/dashboard/keys

Two Modes

1. Generate (text-to-image)

Create images from text prompt only. Script: scripts/generate.sh

2. Edit (image-to-image)

Create images using reference images (up to 14). Script: scripts/edit.sh

Workflow

IMPORTANT: Run generation via Task tool with Haiku subagent to avoid blocking main context.

For Generate mode:

1. •

   Clarify params (if not specified):

   • •Aspect ratio: 1:1, 16:9, 9:16, 4:3, etc.
   • •Resolution: 1K (default), 2K, 4K
2. •

   Propose save path based on project structure:

   • •Check for ./images/, ./assets/, ./static/
   • •Suggest: "Save to ./images/infographic_coffee.png?"
3. •

   Show price & confirm:

   code

   Cost: $0.15/image (4K: $0.30)
   Confirm? (yes/no)
   

4. •

   Launch subagent:

   code

   Task tool:
   - subagent_type: "Bash"
   - model: "haiku"
   - run_in_background: true
   - prompt: Run generate.sh with params
   

5. •

   Report result: Parse JSON output, show image URL, read saved file.

For Edit mode:

1. •

   Get reference images:

   • •If URLs provided → use directly
   • •If local files → run upload.sh first to get URLs
2. •

   Clarify prompt: What to do with references?

3. •

   Show price & confirm: Same as generate

4. •

   Launch subagent with edit.sh

5. •

   Report result

Scripts

generate.sh

sh scripts/generate.sh \
  --prompt "infographic about coffee brewing" \
  --aspect-ratio "9:16" \
  --resolution "1K" \
  --output-dir "./images" \
  --filename "coffee_infographic"

edit.sh

sh scripts/edit.sh \
  --prompt "combine these into a collage" \
  --image-urls "https://example.com/img1.png,https://example.com/img2.png" \
  --aspect-ratio "16:9" \
  --output-dir "./images" \
  --filename "collage"

upload.sh (for local files)

# Get URL for local file
URL=$(sh scripts/upload.sh --file /path/to/image.png)

# Or get base64 data URI (for small files)
URI=$(sh scripts/upload.sh --file /path/to/image.png --base64)

Parallel Generation

For multiple images — launch several subagents in parallel:

Task 1: generate "cat in space" → cat_space.png
Task 2: generate "dog on moon" → dog_moon.png
Task 3: generate "bird in ocean" → bird_ocean.png

Each runs independently via Haiku, results collected when done.

Pricing

• •Generate: $0.15/image
• •Edit: $0.15/edit
• •4K resolution: $0.30 (2x)
• •Web search: +$0.015

Formula: price = num_images * (resolution == "4K" ? 0.30 : 0.15) + (web_search ? 0.015 : 0)

Notes

• •URLs expire in ~1 hour — save locally if needed
• •Uploaded files stored 7 days on fal.ai, then auto-deleted
• •Model excels at text rendering and infographics