/fal-ai-image

Configuration

The skill supports two fal-hosted image models behind the same FAL_KEY:

No separate OpenAI key is required when you use the fal-hosted GPT model.

One-off override from CLI

Both generate.sh and edit.sh support:

--model VALUE

Supported aliases:

Examples:

sh scripts/generate.sh --model gpt --prompt "studio product render"
sh scripts/generate.sh --model gemini --prompt "text-heavy infographic"
sh scripts/edit.sh --model openai --image-urls "$URL" --prompt "premium ad retouch"

Use this when the user explicitly asks for a specific model or asks which options are available.

edit.sh also supports:

--mask-url URL

This is passed through to openai/gpt-image-2/edit and is useful when you want to constrain the edit to a specific region. Nano Banana does not support this flag in the current skill.

Quick start

1. Get an API key at https://fal.ai/dashboard/keys
2. Copy .env.example to .env
3. Set FAL_KEY

Minimal config keeps the old behavior:

FAL_KEY=your_fal_api_key_here

This resolves to Nano Banana Pro automatically.

Switch to OpenAI GPT Image 2

Use the human-friendly selector:

FAL_KEY=your_fal_api_key_here
FAL_IMAGE_PROVIDER=openai
FAL_IMAGE_OPENAI_QUALITY=medium

Or pin the exact fal model ID:

FAL_KEY=your_fal_api_key_here
FAL_IMAGE_MODEL=openai/gpt-image-2
FAL_IMAGE_OPENAI_QUALITY=medium

Selector precedence

Selection in scripts/common.sh is intentionally simple:

1. --model — one-off CLI override
2. FAL_IMAGE_MODEL — exact model override in config
3. FAL_IMAGE_PROVIDER — google or openai
4. Nothing set — fallback to fal-ai/nano-banana-pro

That means older installs with only FAL_KEY keep working without any changes, while a single run can still force GPT or Nano Banana.

Parameter mapping by model

Nano Banana Pro

Native knobs:

• --aspect-ratio
• --resolution
• --web-search (generate only)

OpenAI GPT Image 2

Native knobs:

• --image-size
• --quality
• --mask-url in edit.sh

Supported --image-size forms:

• preset: square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9
• custom size: WIDTHxHEIGHT (for example 1536x1024)
• auto in edit.sh

Compatibility layer:

• if --image-size is omitted, the scripts derive a valid OpenAI image_size from --aspect-ratio + --resolution
• this keeps the old CLI shape usable after switching the provider in config

Quality default for OpenAI

fal's GPT Image 2 schema defaults quality to high, but this skill uses:

FAL_IMAGE_OPENAI_QUALITY=medium

as the default unless you override it via --quality.

Reason: high can make exploratory runs noticeably more expensive than Nano Banana. medium is a safer default for iteration; use --quality high for final renders.

As of April 22, 2026, fal's GPT Image 2 playground shows common high-quality renders landing roughly around $0.15-$0.22 per image depending on size, so the "about $0.18" rule of thumb is reasonable for user guidance. Verify current prices on the model page before promising a number: GPT Image 2 pricing.

Examples

Default Nano Banana

sh scripts/generate.sh \
  --prompt "poster about coffee brewing" \
  --aspect-ratio "9:16" \
  --resolution "1K"

OpenAI GPT Image 2 with explicit preset size

sh scripts/generate.sh \
  --model "gpt" \
  --prompt "realistic product hero shot, clean label typography" \
  --image-size "landscape_4_3" \
  --quality "medium"

OpenAI GPT Image 2 while keeping old flags

sh scripts/generate.sh \
  --model "openai" \
  --prompt "editorial-style fashion photo" \
  --aspect-ratio "4:3" \
  --resolution "2K"

The script will derive a valid image_size object for OpenAI automatically.

Troubleshooting

FAL_KEY not found

Set FAL_KEY in config/.env or the shell environment.

Unsupported FAL_IMAGE_PROVIDER

Use only:

FAL_IMAGE_PROVIDER=google
FAL_IMAGE_PROVIDER=openai

Unsupported FAL_IMAGE_MODEL

Use only:

FAL_IMAGE_MODEL=fal-ai/nano-banana-pro
FAL_IMAGE_MODEL=openai/gpt-image-2

OpenAI image_size width and height must be multiples of 16

When you pass custom --image-size, use dimensions like:

• 1024x1024
• 1536x1024
• 1920x1088

References

• Nano Banana Pro API: https://fal.ai/models/fal-ai/nano-banana-pro/api
• Nano Banana Pro edit API: https://fal.ai/models/fal-ai/nano-banana-pro/edit/api
• GPT Image 2 API: https://fal.ai/models/openai/gpt-image-2/api
• GPT Image 2 edit API: https://fal.ai/models/openai/gpt-image-2/edit/api