fal-ai-image Skill | Agent Skills

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:

Clarify params (if not specified):
- Aspect ratio: 1:1, 16:9, 9:16, 4:3, etc.
- Resolution: 1K (default), 2K, 4K
Propose save path based on project structure:
- Check for ./images/, ./assets/, ./static/
- Suggest: "Save to ./images/infographic_coffee.png?"

Show price & confirm:

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

Launch subagent:

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

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

For Edit mode:

Get reference images:
- If URLs provided → use directly
- If local files → run upload.sh first to get URLs
Clarify prompt: What to do with references?
Show price & confirm: Same as generate
Launch subagent with edit.sh
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"

| Param | Required | Default | Values | |-------|----------|---------|--------| | --prompt | yes | - | text | | --aspect-ratio | no | 1:1 | 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16 | | --resolution | no | 1K | 1K, 2K, 4K | | --num-images | no | 1 | 1-4 | | --output-dir | no | - | path | | --filename | no | generated | base name | | --web-search | no | false | flag |

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"

| Param | Required | Default | Values | |-------|----------|---------|--------| | --prompt | yes | - | text | | --image-urls | yes | - | comma-separated URLs (max 14) | | --aspect-ratio | no | auto | auto, 1:1, 16:9, etc. | | --resolution | no | 1K | 1K, 2K, 4K | | --num-images | no | 1 | 1-4 variations | | --output-dir | no | - | path | | --filename | no | edited | base name |

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

Agent Skills: fal-ai-image

Install this agent skill to your local

Skill Files