fal.ai Image Generation & Editing Skill

Professional AI-powered image workflows: generate, remix, and edit using fal.ai's state-of-the-art models.

Three Powerful Tools

1. Text-to-Image: Generate from Scratch

uv run python fal-text-to-image "A serene mountain landscape at sunset"

2. Image Remix: Transform Existing Images

uv run python fal-image-remix photo.jpg "Transform into oil painting"

3. Image Edit: Targeted Modifications

uv run python fal-image-edit photo.jpg mask.png "Replace with flowers"

Quick Start

Text-to-Image

# Basic generation (auto-selects best model)
uv run python fal-text-to-image "Cyberpunk city at sunset"

# With specific model
uv run python fal-text-to-image -m flux-pro/v1.1-ultra "Professional portrait"

# With style reference
uv run python fal-text-to-image -i reference.jpg "Artistic landscape"

Image Remix

# Basic remix (auto-selects model)
uv run python fal-image-remix input.jpg "Anime style character"

# Control transformation strength (0.0=preserve, 1.0=full transformation)
uv run python fal-image-remix photo.jpg "Watercolor painting" --strength 0.6

# Premium quality
uv run python fal-image-remix -m flux-1.1-pro image.jpg "Professional studio portrait"

Image Edit

# Edit with mask image (white=edit, black=preserve)
uv run python fal-image-edit photo.jpg mask.png "Replace with garden"

# Auto-generate mask from text
uv run python fal-image-edit photo.jpg --mask-prompt "sky" "Make it sunset"

# Remove objects
uv run python fal-image-edit image.jpg mask.png "Remove" --strength 1.0

# General editing (no mask)
uv run python fal-image-edit photo.jpg "Enhance lighting and colors"

Setup

1. Get your API key from fal.ai dashboard

2. Set environment variable:

export FAL_KEY="your-api-key-here"

Or create .env file:

FAL_KEY=your-api-key-here

1. Run (uv handles dependencies automatically):

# Text-to-image
uv run python fal-text-to-image "Your prompt here"

# Image remix
uv run python fal-image-remix input.jpg "Your transformation prompt"

# Image edit
uv run python fal-image-edit input.jpg mask.png "Your edit prompt"

Features

Text-to-Image

• Intelligent Model Selection: Auto-selects best model based on prompt analysis
• 13+ Model Options: FLUX, Recraft V3, Imagen4, Stable Diffusion, and more
• Style Transfer: Use reference images with -i flag
• High-Resolution: Up to 2K outputs with flux-pro/v1.1-ultra
• Reproducible: Use --seed for consistent results

Image Remix

• Style Transformation: Convert photos to paintings, illustrations, or any artistic style
• Strength Control: Adjust transformation intensity (0.0-1.0)
• Composition Preservation: Maintains original image structure while applying new styles
• Multiple Models: Optimized for different remix types (artistic, realistic, vector)

Image Edit

• Targeted Editing: Modify specific regions using mask images
• Auto-Masking: Generate masks from text prompts (--mask-prompt)
• Object Removal: Seamlessly remove unwanted objects
• Inpainting: Fill and complete image regions
• General Editing: Overall image adjustments without masks

All Tools

• Metadata Embedding: Stores prompt and generation parameters in image EXIF
• Progress Tracking: Real-time queue position and generation status
• Error Handling: Clear error messages and validation

Available Models

See SKILL.md for complete model documentation.

Text-to-Image Top Picks

• flux-pro/v1.1-ultra: Professional high-res (up to 2K)
• recraft/v3/text-to-image: SOTA quality, excellent typography
• flux-2: Best balance (100 free requests)
• ideogram/v2: Typography specialist

Image Remix Top Picks

• flux-2/dev: General remixing (free, fast)
• flux-1.1-pro: Premium quality transformations
• recraft/v3: Vector/illustration style
• stable-diffusion-v35: Artistic styles

Image Edit Top Picks

• flux-2/fill: Seamless inpainting (default)
• flux-pro-v11/fill: Premium quality inpainting
• flux-2/redux: General editing (no mask)
• stable-diffusion-v35/inpainting: Artistic edits

Usage Examples

Text-to-Image

Typography & Logos

uv run python fal-text-to-image \
  -m recraft/v3/text-to-image \
  "Modern tech logo with text 'AI Labs' in minimalist blue design"

Professional Photography

uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  "Professional headshot of business executive, studio lighting, grey background"

Reproducible Generation

uv run python fal-text-to-image \
  -m flux-2 \
  --seed 42 \
  "Cyberpunk cityscape with neon lights"

Image Remix

Style Transfer

# Subtle artistic style
uv run python fal-image-remix photo.jpg "Oil painting style" --strength 0.4

# Strong anime transformation
uv run python fal-image-remix portrait.jpg "Anime character" --strength 0.9

# Vector conversion
uv run python fal-image-remix -m recraft/v3 logo.png "Clean vector illustration"

Image Edit

Object Removal

# Remove with mask
uv run python fal-image-edit photo.jpg object_mask.png "Remove completely" --strength 1.0

Region Replacement

# With mask image
uv run python fal-image-edit room.jpg region_mask.png "Add modern sofa"

# With auto-generated mask
uv run python fal-image-edit landscape.jpg --mask-prompt "sky" "Golden hour sunset"

General Enhancement

uv run python fal-image-edit -m flux-2/redux photo.jpg "Enhance lighting and saturation"

Workflow Pipeline

Combine all three tools for complete image workflows:

# 1. Generate base image
uv run python fal-text-to-image "Modern office space" -o base.png

# 2. Apply artistic style
uv run python fal-image-remix base.png "Cyberpunk aesthetic" -o styled.png

# 3. Edit specific details
uv run python fal-image-edit styled.png --mask-prompt "desk" "Add holographic display"

Command-Line Options

fal-text-to-image

Arguments:
  PROMPT                    Text description of image

Options:
  -m, --model TEXT         Model selection
  -i, --image TEXT         Reference image for style transfer
  -o, --output TEXT        Output filename
  -s, --size TEXT          Image size (1024x1024, landscape_16_9, etc.)
  --seed INTEGER           Random seed
  --steps INTEGER          Inference steps
  --guidance FLOAT         Guidance scale
  --help                   Show help

fal-image-remix

Arguments:
  INPUT_IMAGE              Path or URL to source image
  PROMPT                   How to transform the image

Options:
  -m, --model TEXT         Model selection
  -o, --output TEXT        Output filename
  -s, --strength FLOAT     Transformation strength 0.0-1.0 (default: 0.75)
  --guidance FLOAT         Guidance scale (default: 7.5)
  --seed INTEGER           Random seed
  --steps INTEGER          Inference steps
  --help                   Show help

fal-image-edit

Arguments:
  INPUT_IMAGE              Path or URL to source image
  MASK_IMAGE               Path or URL to mask (white=edit, black=preserve) [optional]
  PROMPT                   How to edit the masked region

Options:
  -m, --model TEXT         Model selection
  -o, --output TEXT        Output filename
  --mask-prompt TEXT       Generate mask from text (no mask image needed)
  -s, --strength FLOAT     Edit strength 0.0-1.0 (default: 0.95)
  --guidance FLOAT         Guidance scale (default: 7.5)
  --seed INTEGER           Random seed
  --steps INTEGER          Inference steps
  --help                   Show help

Output

All tools save images to outputs/ directory with:

• Timestamp in filename
• Model name in filename
• Embedded metadata (prompt, model, parameters)
• Console display of generation time and image URL

Cost Management

• Free Tier: flux-2/dev offers 100 free requests (until Dec 25, 2025)
• Budget: Use flux-2/dev or stable-diffusion models
• Premium: flux-pro models charged per megapixel
• Design: recraft/v3 at $0.04/image ($0.08 for vector)

Monitor usage at fal.ai dashboard

File Structure

fal-text-to-image/
├── SKILL.md                    # Full documentation
├── README.md                   # This file
├── fal-text-to-image           # Text-to-image generation script
├── fal-image-remix             # Image-to-image remixing script
├── fal-image-edit              # Image editing/inpainting script
├── pyproject.toml              # Dependencies
├── .env.example                # Environment template
├── .gitignore
├── references/
│   └── model-comparison.md     # Detailed model comparison
└── outputs/                    # Generated images (created on first run)

Troubleshooting

Resources

• fal.ai Documentation
• Model Playground
• API Keys
• Pricing
• Full Skill Documentation

Dependencies

Managed automatically by uv:

• fal-client
• python-dotenv
• pillow
• click
• requests

License

This skill is part of the Claude Code skills ecosystem.