Fal Text-to-Image

Generate, remix, and edit images using fal.ai's AI models. Supports text-to-image generation, image-to-image remixing, and targeted inpainting/editing.

delorenj@delorenj

Install

openclaw skills install @delorenj/fal-text-to-image

fal.ai Image Generation & Editing Skill

Professional AI-powered image workflows using fal.ai's state-of-the-art models including FLUX, Recraft V3, Imagen4, and more.

Three Modes of Operation

1. Text-to-Image (fal-text-to-image)

Generate images from scratch using text prompts

2. Image Remix (fal-image-remix)

Transform existing images while preserving composition

3. Image Edit (fal-image-edit)

Targeted inpainting and masked editing

When to Use This Skill

Trigger when user:

Requests image generation from text descriptions
Wants to transform/remix existing images with AI
Needs to edit specific regions of images (inpainting)
Wants to create images with specific styles (vector, realistic, typography)
Needs high-resolution professional images (up to 2K)
Wants to use a reference image for style transfer
Mentions specific models like FLUX, Recraft, or Imagen
Asks for logo, poster, or brand-style image generation
Needs object removal or targeted modifications

Quick Start

Text-to-Image: Generate from Scratch

bash

# Basic generation
uv run python fal-text-to-image "A cyberpunk city at sunset with neon lights"

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

# With style reference
uv run python fal-text-to-image -i reference.jpg "Mountain landscape" -m flux-2/lora/edit

Image Remix: Transform Existing Images

bash

# Transform style while preserving composition
uv run python fal-image-remix input.jpg "Transform into oil painting"

# With strength control (0.0=original, 1.0=full transformation)
uv run python fal-image-remix photo.jpg "Anime style character" --strength 0.6

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

Image Edit: Targeted Modifications

bash

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

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

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

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

Model Selection Guide

The script intelligently selects the best model based on task context:

flux-pro/v1.1-ultra (Default for High-Res)

Best for: Professional photography, high-resolution outputs (up to 2K)
Strengths: Photo realism, professional quality
Use when: User needs publication-ready images
Endpoint: fal-ai/flux-pro/v1.1-ultra

recraft/v3/text-to-image (SOTA Quality)

Best for: Typography, vector art, brand-style images, long text
Strengths: Industry-leading benchmark scores, precise text rendering
Use when: Creating logos, posters, or text-heavy designs
Endpoint: fal-ai/recraft/v3/text-to-image

flux-2 (Best Balance)

Best for: General-purpose image generation
Strengths: Enhanced realism, crisp text, native editing
Use when: Standard image generation needs
Endpoint: fal-ai/flux-2

flux-2/lora (Custom Styles)

Best for: Domain-specific styles, fine-tuned variations
Strengths: Custom style adaptation
Use when: User wants specific artistic styles
Endpoint: fal-ai/flux-2/lora

flux-2/lora/edit (Style Transfer)

Best for: Image-to-image editing with style references
Strengths: Specialized style transfer
Use when: User provides reference image with -i flag
Endpoint: fal-ai/flux-2/lora/edit

imagen4/preview (Google Quality)

Best for: High-quality general images
Strengths: Google's highest quality model
Use when: User specifically requests Imagen or Google models
Endpoint: fal-ai/imagen4/preview

stable-diffusion-v35-large (Typography & Style)

Best for: Complex prompts, typography, style control
Strengths: Advanced prompt understanding, resource efficiency
Use when: Complex multi-element compositions
Endpoint: fal-ai/stable-diffusion-v35-large

ideogram/v2 (Typography Specialist)

Best for: Posters, logos, text-heavy designs
Strengths: Exceptional typography, realistic outputs
Use when: Text accuracy is critical
Endpoint: fal-ai/ideogram/v2

bria/text-to-image/3.2 (Commercial Safe)

Best for: Commercial projects requiring licensed training data
Strengths: Safe for commercial use, excellent text rendering
Use when: Legal/licensing concerns matter
Endpoint: fal-ai/bria/text-to-image/3.2

Command-Line Interface

bash

uv run python fal-text-to-image [OPTIONS] PROMPT

Arguments:
  PROMPT                    Text description of the image to generate

Options:
  -m, --model TEXT         Model to use (see model list above)
  -i, --image TEXT         Path or URL to reference image for style transfer
  -o, --output TEXT        Output filename (default: generated_image.png)
  -s, --size TEXT          Image size (e.g., "1024x1024", "landscape_16_9")
  --seed INTEGER           Random seed for reproducibility
  --steps INTEGER          Number of inference steps (model-dependent)
  --guidance FLOAT         Guidance scale (higher = more prompt adherence)
  --help                   Show this message and exit

Authentication Setup

Before first use, set your fal.ai API key:

bash

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

Or create a .env file in the skill directory:

env

FAL_KEY=your-api-key-here

Get your API key from: https://fal.ai/dashboard/keys

Advanced Examples

High-Resolution Professional Photo

bash

uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  "Professional headshot of a business executive in modern office" \
  -s 2048x2048

Logo/Typography Design

bash

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

Style Transfer from Reference

bash

uv run python fal-text-to-image \
  -m flux-2/lora/edit \
  -i artistic_style.jpg \
  "Portrait of a woman in a garden"

Reproducible Generation

bash

uv run python fal-text-to-image \
  -m flux-2 \
  --seed 42 \
  "Futuristic cityscape with flying cars"

Model Selection Logic

The script automatically selects the best model when -m is not specified:

If -i provided: Uses flux-2/lora/edit for style transfer
If prompt contains typography keywords (logo, text, poster, sign): Uses recraft/v3/text-to-image
If prompt suggests high-res needs (professional, portrait, headshot): Uses flux-pro/v1.1-ultra
If prompt mentions vector/brand: Uses recraft/v3/text-to-image
Default: Uses flux-2 for general purpose

Output Format

Generated images are saved with metadata:

Filename includes timestamp and model name
EXIF data stores prompt, model, and parameters
Console displays generation time and cost estimate

Troubleshooting

Problem	Solution
`FAL_KEY not set`	Export FAL_KEY environment variable or create .env file
`Model not found`	Check model name against supported list
`Image reference fails`	Ensure image path/URL is accessible
`Generation timeout`	Some models take longer; wait or try faster model
`Rate limit error`	Check fal.ai dashboard for usage limits

Cost Optimization

Free tier: FLUX.2 offers 100 free requests (expires Dec 25, 2025)
Pay per use: FLUX Pro charges per megapixel
Budget option: Use flux-2 or stable-diffusion-v35-large for general use
Premium: Use flux-pro/v1.1-ultra only when high-res is required

Image Remix: Model Selection Guide

Available models for image-to-image remixing:

flux-2/dev (Default, Free)

Best for: General remixing, style transfer, fast iteration
Strengths: Balanced quality/speed, 100 free requests
Use when: Standard remixing needs
Endpoint: fal-ai/flux/dev/image-to-image

flux-pro (Premium Quality)

Best for: Professional remixing, high-quality outputs
Strengths: Superior quality, realistic transformations
Use when: Professional or publication-ready remixes
Endpoint: fal-ai/flux-pro

flux-1.1-pro (Ultra Premium)

Best for: Highest quality remixing with maximum detail
Strengths: Ultra-high quality, exceptional detail preservation
Use when: Premium projects requiring best possible output
Endpoint: fal-ai/flux-pro/v1.1

recraft/v3 (Vector/Illustration)

Best for: Vector style, brand imagery, illustration remixing
Strengths: Clean vector outputs, brand-style transformations
Use when: Converting to illustration or vector style
Endpoint: fal-ai/recraft/v3/text-to-image

stable-diffusion-v35 (Artistic)

Best for: Artistic styles, painting effects, creative remixing
Strengths: Strong artistic style application
Use when: Artistic or stylized transformations
Endpoint: fal-ai/stable-diffusion-v35-large

Image Remix: Command-Line Interface

bash

uv run python fal-image-remix [OPTIONS] INPUT_IMAGE PROMPT

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

Options:
  -m, --model TEXT         Model to use (auto-selected if not specified)
  -o, --output TEXT        Output filename (default: remixed_TIMESTAMP.png)
  -s, --strength FLOAT     Transformation strength 0.0-1.0 (default: 0.75)
                           0.0 = preserve original, 1.0 = full transformation
  --guidance FLOAT         Guidance scale (default: 7.5)
  --seed INTEGER           Random seed for reproducibility
  --steps INTEGER          Number of inference steps
  --help                   Show help

Remix Strength Guide

The --strength parameter controls transformation intensity:

Strength	Effect	Use Case
0.3-0.5	Subtle changes	Minor color adjustments, lighting tweaks
0.5-0.7	Moderate changes	Style hints while preserving details
0.7-0.85	Strong changes	Clear style transfer, significant transformation
0.85-1.0	Maximum changes	Complete style overhaul, dramatic transformation

Remix Examples

bash

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

# Balanced transformation (default)
uv run python fal-image-remix input.jpg "Cyberpunk neon aesthetic"

# Strong transformation (high strength)
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"

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

Image Edit: Model Selection Guide

Available models for targeted editing and inpainting:

flux-2/redux (General Editing)

Best for: General image editing without masks
Strengths: Fast, balanced, good for overall adjustments
Use when: No specific region targeting needed
Endpoint: fal-ai/flux-2/redux

flux-2/fill (Inpainting, Default)

Best for: Masked region editing, object removal, filling
Strengths: Seamless inpainting, natural blending
Use when: Editing specific masked regions
Endpoint: fal-ai/flux-2/fill

flux-pro-v11/fill (Premium Inpainting)

Best for: Professional inpainting with highest quality
Strengths: Superior quality, professional results
Use when: Premium quality inpainting required
Endpoint: fal-ai/flux-pro-v11/fill

stable-diffusion-v35/inpainting (Artistic Inpainting)

Best for: Artistic edits, creative inpainting
Strengths: Strong artistic control, detailed generation
Use when: Artistic or stylized edits
Endpoint: fal-ai/stable-diffusion-v35-large/inpainting

ideogram/v2/edit (Realistic Editing)

Best for: Realistic modifications, precise edits
Strengths: High realism, precise control
Use when: Realistic edits required
Endpoint: fal-ai/ideogram/v2/edit

recraft/v3/svg (Vector Editing)

Best for: Vector style edits, clean illustrations
Strengths: Clean vector outputs, illustration style
Use when: Vector or illustration edits
Endpoint: fal-ai/recraft/v3/svg

Image Edit: Command-Line Interface

bash

uv run python fal-image-edit [OPTIONS] INPUT_IMAGE [MASK_IMAGE] PROMPT

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 to use (auto-selected if not specified)
  -o, --output TEXT        Output filename (default: edited_TIMESTAMP.png)
  --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 for reproducibility
  --steps INTEGER          Number of inference steps
  --help                   Show help

Edit Strength Guide

The --strength parameter controls edit intensity:

Strength	Effect	Use Case
0.5-0.7	Subtle edits	Minor touch-ups, color adjustments
0.7-0.9	Moderate edits	Clear modifications while blending naturally
0.9-1.0	Strong edits	Complete replacement, object removal

Creating Mask Images

Mask images define edit regions:

White (255): Areas to edit/modify
Black (0): Areas to preserve unchanged
Gray: Partial blending (proportional to brightness)

Create masks using:

Image editors (GIMP, Photoshop, Krita)
Paint tools (select and fill with white/black)
Text-based prompts (--mask-prompt flag)

Edit Examples

bash

# Edit with mask image
uv run python fal-image-edit photo.jpg mask.png "Replace with beautiful garden"

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

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

# Seamless object insertion
uv run python fal-image-edit room.jpg region_mask.png "Add modern sofa" --strength 0.85

# General editing (no mask)
uv run python fal-image-edit -m flux-2/redux photo.jpg "Enhance lighting and saturation"

# Premium quality inpainting
uv run python fal-image-edit -m flux-pro-v11/fill image.jpg mask.png "Professional portrait background"

# Artistic modification
uv run python fal-image-edit -m stable-diffusion-v35/inpainting photo.jpg mask.png "Van Gogh style"

File Structure

text

fal-text-to-image/
├── SKILL.md                    # This file
├── README.md                   # Quick reference
├── pyproject.toml              # Dependencies (uv)
├── fal-text-to-image           # Text-to-image generation script
├── fal-image-remix             # Image-to-image remixing script
├── fal-image-edit              # Image editing/inpainting script
├── references/
│   └── model-comparison.md     # Detailed model benchmarks
└── outputs/                    # Generated images (created on first run)

Dependencies

Managed via uv:

fal-client: Official fal.ai Python SDK
python-dotenv: Environment variable management
pillow: Image handling and EXIF metadata
click: CLI interface

Best Practices

General

Model Selection: Let scripts auto-select unless you have specific needs
Prompt Engineering: Be specific and descriptive for better outputs
Cost Awareness: Monitor usage on fal.ai dashboard
Reproducibility: Use --seed for consistent results during iteration

Text-to-Image

Reference Images: Use high-quality references for best style transfer results
Size Selection: Match aspect ratio to intended use (square, landscape, portrait)
Model Choice: Use recraft/v3 for typography, flux-pro for professional photography

Image Remix

Strength Tuning: Start with default (0.75), adjust based on desired transformation
Source Quality: Higher quality source images produce better remixes
Iteration: Use --seed to iterate on same generation with different prompts
Balance: Lower strength preserves more detail, higher creates more dramatic changes

Image Edit

Mask Quality: Clean, well-defined masks produce better results
Mask Creation: Use image editors for precise control, --mask-prompt for quick tests
Blending: Use gray tones in masks for smooth transitions
Edit Strength: Use 0.95+ for object removal, 0.7-0.9 for modifications
Test First: Try --mask-prompt before creating detailed masks
Multiple Edits: Edit in stages rather than all at once for complex modifications

Resources

fal.ai Documentation: https://docs.fal.ai/
Model Playground: https://fal.ai/explore/search
API Keys: https://fal.ai/dashboard/keys
Pricing: https://fal.ai/pricing

Workflow Examples

Complete Image Creation Pipeline

bash

# 1. Generate base image
uv run python fal-text-to-image -m flux-2 "Modern office space, minimalist" -o base.png

# 2. Remix to different style
uv run python fal-image-remix base.png "Cyberpunk aesthetic with neon" -o styled.png

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

Iterative Refinement

bash

# Generate with seed for reproducibility
uv run python fal-text-to-image "Mountain landscape" --seed 42 -o v1.png

# Remix with same seed, different style
uv run python fal-image-remix v1.png "Oil painting style" --seed 42 -o v2.png

# Fine-tune with editing
uv run python fal-image-edit v2.png --mask-prompt "sky" "Golden hour lighting" --seed 42

Object Removal and Replacement

bash

# 1. Remove unwanted object
uv run python fal-image-edit photo.jpg object_mask.png "Remove" --strength 1.0 -o removed.png

# 2. Fill with new content
uv run python fal-image-edit removed.png region_mask.png "Beautiful flowers" --strength 0.9

Troubleshooting

Problem	Solution	Tool
`FAL_KEY not set`	Export FAL_KEY or create .env file	All
`Model not found`	Check model name in documentation	All
`Image upload fails`	Check file exists and is readable	Remix, Edit
`Mask not working`	Verify mask is grayscale PNG (white=edit)	Edit
`Transformation too strong`	Reduce --strength value	Remix, Edit
`Transformation too weak`	Increase --strength value	Remix, Edit
`Mask-prompt not precise`	Create manual mask in image editor	Edit
`Generation timeout`	Try faster model or wait longer	All
`Rate limit error`	Check fal.ai dashboard usage limits	All

Limitations

General

Requires active fal.ai API key
Subject to fal.ai rate limits and quotas
Internet connection required
Some models have usage costs (check pricing)

Text-to-Image

Image reference features limited to specific models
Typography quality varies by model

Image Remix

Source image quality affects output quality
Extreme strength values may introduce artifacts
Some styles work better with specific models

Image Edit

Mask quality critical for seamless results
Auto-generated masks (--mask-prompt) less precise than manual masks
Complex edits may require multiple passes
Some models don't support all editing features

Fal Text-to-Image

Install

fal.ai Image Generation & Editing Skill

Three Modes of Operation

1. Text-to-Image (fal-text-to-image)

2. Image Remix (fal-image-remix)

3. Image Edit (fal-image-edit)

When to Use This Skill

Quick Start

Text-to-Image: Generate from Scratch

Image Remix: Transform Existing Images

Image Edit: Targeted Modifications

Model Selection Guide

flux-pro/v1.1-ultra (Default for High-Res)

recraft/v3/text-to-image (SOTA Quality)

flux-2 (Best Balance)

flux-2/lora (Custom Styles)

flux-2/lora/edit (Style Transfer)

imagen4/preview (Google Quality)

stable-diffusion-v35-large (Typography & Style)

ideogram/v2 (Typography Specialist)

bria/text-to-image/3.2 (Commercial Safe)

Command-Line Interface

Authentication Setup

Advanced Examples

High-Resolution Professional Photo

Logo/Typography Design

Style Transfer from Reference

Reproducible Generation

Model Selection Logic

Output Format

Troubleshooting

Cost Optimization

Image Remix: Model Selection Guide

flux-2/dev (Default, Free)

flux-pro (Premium Quality)

flux-1.1-pro (Ultra Premium)

recraft/v3 (Vector/Illustration)

stable-diffusion-v35 (Artistic)

Image Remix: Command-Line Interface

Remix Strength Guide

Remix Examples

Image Edit: Model Selection Guide

flux-2/redux (General Editing)

flux-2/fill (Inpainting, Default)

flux-pro-v11/fill (Premium Inpainting)

stable-diffusion-v35/inpainting (Artistic Inpainting)

ideogram/v2/edit (Realistic Editing)

recraft/v3/svg (Vector Editing)

Image Edit: Command-Line Interface

Edit Strength Guide

Creating Mask Images

Edit Examples

File Structure

Dependencies

Best Practices

General

Text-to-Image

Image Remix

Image Edit

Resources

Workflow Examples

Complete Image Creation Pipeline

Iterative Refinement

Object Removal and Replacement

Troubleshooting

Limitations

General

Text-to-Image

Image Remix

Image Edit

Related skills