Fal AI Image Skill for Claude

fal-ai-image

Generate images via fal.ai. The skill now supports two fal-hosted models:

• Google Nano Banana Pro (fal-ai/nano-banana-pro) — default, backward-compatible
• OpenAI GPT Image 2 (openai/gpt-image-2) — enabled from config/.env

Synonyms the agent should treat as equivalent:

• gpt = openai = GPT Image 2
• nano banana = google = gemini = Nano Banana Pro

Best for: infographics, text rendering, banners, photo edits, reference-based compositions.

STOP — Read Before Acting

• DO NOT use Pillow, ImageMagick, or post-processing for text/logo overlay unless the user explicitly asked for that workflow
• DO NOT use Generate mode when the user provided reference images — use Edit mode
• DO NOT assume GPT is active — check config/README.md logic; if no selector is configured, the skill stays on Nano Banana
• DO NOT guess provider-specific params — Nano Banana and GPT Image 2 use different schemas
• DO pass --model ... when the user explicitly asks for a specific model/provider or asks to compare providers
• DO NOT skip uploading local files — run upload.sh first to get URLs for edit.sh

Quick Start Decision

Reference images provided?  -> Edit mode   (upload.sh -> edit.sh)
Text-only generation?       -> Generate mode (generate.sh)

Model comes from config/.env:
  no selector set           -> Nano Banana Pro
  FAL_IMAGE_PROVIDER=openai -> GPT Image 2
  FAL_IMAGE_MODEL=...       -> exact override

Config

Requires FAL_KEY in config/.env or the environment.

Model selection:

• --model — one-off override for the current command
• FAL_IMAGE_MODEL — exact override in config
• FAL_IMAGE_PROVIDER — google or openai
• nothing set — default to Nano Banana Pro

Use --model whenever the user explicitly says things like:

• "сделай через GPT"
• "используй OpenAI"
• "сделай через Google / Gemini / Nano Banana"
• "какие тут есть провайдеры?"

Answer that the skill supports two choices and map the command like this:

• --model gpt for OpenAI GPT Image 2
• --model gemini or --model nano-banana for Nano Banana

OpenAI quality default:

• FAL_IMAGE_OPENAI_QUALITY=medium unless overridden with --quality
• this skill intentionally uses medium as the default for GPT to avoid expensive exploratory runs

Full setup and troubleshooting: config/README.md.

Read references only when needed:

• references/MODELS.md — selector precedence, aliases, cost heuristics
• references/EDITING.md — generate vs edit, mask_url, inpainting behavior

Model Notes

Nano Banana Pro

Strengths:

• lower-friction default for existing installs
• strong text rendering, including Cyrillic
• good at infographics, banners, and mixed text/image layouts
• supports --web-search in generate mode

Main params:

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

OpenAI GPT Image 2

Strengths:

• stronger prompt adherence and fine-grained edits
• better photorealism and product-style renders
• native quality control
• uses the same FAL_KEY through fal, no separate OpenAI key
• current fal pricing is size/quality-dependent; a rough high-quality mental model is about $0.18 per image, but check the live model page before quoting an exact number

Main params:

• --image-size
• --quality

Compatibility layer:

• if --image-size is omitted, the scripts derive a valid OpenAI image_size from --aspect-ratio + --resolution
• this lets old prompts continue working after the provider switch in config

Workflow

Generate mode

• Decide model from config
• Clarify missing params only if needed:
• Nano Banana: aspect ratio, resolution
• GPT Image 2: image size and quality
• Propose save path based on project structure
• Run generate.sh
• Parse result JSON, report URL and local files if downloaded

Edit mode

• Get reference images:
• URL already available -> use directly
• local file -> upload.sh
• Decide model from config
• Clarify edit intent
• Run edit.sh
• Parse result JSON, report URL and local files if downloaded

Scripts

generate.sh

Nano Banana example:

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

GPT Image 2 example:

sh scripts/generate.sh \
  --model "gpt" \
  --prompt "realistic product hero shot with sharp packaging text" \
  --image-size "landscape_4_3" \
  --quality "medium" \
  --output-dir "./images" \
  --filename "product_hero"

Compatibility example for GPT:

sh scripts/generate.sh \
  --model "openai" \
  --prompt "editorial portrait, window light, magazine cover layout" \
  --aspect-ratio "4:3" \
  --resolution "2K"

| Param | Required | Default | Notes |

|-------|----------|---------|-------|

| --prompt | yes | - | text prompt |

| --model | no | config / Nano Banana fallback | nano-banana, google, gemini, gpt, openai, or exact endpoint |

| --aspect-ratio | no | 1:1 | Nano native; for GPT used only when --image-size is omitted |

| --resolution | no | 1K | Nano native; for GPT used only when --image-size is omitted |

| --image-size | no | derived from ratio/resolution | GPT only; preset (landscape_4_3) or WIDTHxHEIGHT |

| --quality | no | medium via config | GPT only; low, medium, high |

| --num-images | no | 1 | 1-4 |

| --output-format | no | png | jpeg, png, webp |

| --output-dir | no | - | local path |

| --filename | no | generated | base filename |

| --web-search | no | false | Nano only; ignored for GPT |

edit.sh

Nano Banana example:

sh scripts/edit.sh \
  --model "gemini" \
  --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"

GPT Image 2 example:

sh scripts/edit.sh \
  --model "gpt" \
  --prompt "make this product shot look like a premium studio campaign" \
  --image-urls "https://example.com/source.png" \
  --mask-url "https://example.com/mask.png" \
  --image-size "auto" \
  --quality "medium" \
  --output-dir "./images" \
  --filename "studio_edit"

| Param | Required | Default | Notes |

|-------|----------|---------|-------|

| --prompt | yes | - | edit instruction |

| --image-urls | yes | - | comma-separated URLs |

| --model | no | config / Nano Banana fallback | nano-banana, google, gemini, gpt, openai, or exact endpoint |

| --mask-url | no | - | GPT edit only; optional mask for targeted edits |

| --aspect-ratio | no | auto | Nano native; for GPT used only when --image-size is omitted |

| --resolution | no | 1K | Nano native; for GPT used only when --image-size is omitted |

| --image-size | no | derived from ratio/resolution / auto | GPT only |

| --quality | no | medium via config | GPT only |

| --num-images | no | 1 | 1-4 |

| --output-format | no | png | jpeg, png, webp |

| --output-dir | no | - | local path |

| --filename | no | edited | base filename |

upload.sh

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

# Get base64 data URI for manual API work
URI=$(sh scripts/upload.sh --file /path/to/image.png --base64)

Cost Guidance

• Nano Banana Pro is the cheaper and safer default for quick iterations
• GPT Image 2 cost depends heavily on quality and image_size
• this skill defaults GPT to medium quality to reduce surprise spend

For current pricing, check fal's model pages in config/README.md.

Notes

• result URLs expire in roughly one hour — download locally if you need persistence
• uploaded files on fal storage are temporary
• edit.sh now polls the same /edit queue endpoints documented by fal