fal-text-to-image

Original source / Raw SKILL.md

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

# 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:

1. **If `-i` provided**: Uses `flux-2/lora/edit` for style transfer
2. **If prompt contains typography keywords** (logo, text, poster, sign): Uses `recraft/v3/text-to-image`
3. **If prompt suggests high-res needs** (professional, portrait, headshot): Uses `flux-pro/v1.1-ultra`
4. **If prompt mentions vector/brand**: Uses `recraft/v3/text-to-image`
5. **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

```
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
1. **Model Selection**: Let scripts auto-select unless you have specific needs
2. **Prompt Engineering**: Be specific and descriptive for better outputs
3. **Cost Awareness**: Monitor usage on fal.ai dashboard
4. **Reproducibility**: Use `--seed` for consistent results during iteration

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

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

### Image Edit
1. **Mask Quality**: Clean, well-defined masks produce better results
2. **Mask Creation**: Use image editors for precise control, --mask-prompt for quick tests
3. **Blending**: Use gray tones in masks for smooth transitions
4. **Edit Strength**: Use 0.95+ for object removal, 0.7-0.9 for modifications
5. **Test First**: Try --mask-prompt before creating detailed masks
6. **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


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# 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
```bash
uv run python fal-text-to-image "A serene mountain landscape at sunset"
```

### 2. Image Remix: Transform Existing Images
```bash
uv run python fal-image-remix photo.jpg "Transform into oil painting"
```

### 3. Image Edit: Targeted Modifications
```bash
uv run python fal-image-edit photo.jpg mask.png "Replace with flowers"
```

## Quick Start

### Text-to-Image
```bash
# 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
```bash
# 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
```bash
# 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](https://fal.ai/dashboard/keys)

2. Set environment variable:
```bash
export FAL_KEY="your-api-key-here"
```

Or create `.env` file:
```env
FAL_KEY=your-api-key-here
```

3. Run (uv handles dependencies automatically):
```bash
# 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](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
```bash
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
```bash
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  "Professional headshot of business executive, studio lighting, grey background"
```

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

### Image Remix

#### Style Transfer
```bash
# 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
```bash
# Remove with mask
uv run python fal-image-edit photo.jpg object_mask.png "Remove completely" --strength 1.0
```

#### Region Replacement
```bash
# 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
```bash
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:

```bash
# 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](https://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

| Issue | Solution | Tool |
|-------|----------|------|
| `FAL_KEY not set` | Export FAL_KEY or create .env file | All |
| `Model not found` | Check model name in SKILL.md | 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 |
| `Generation timeout` | Try faster model or wait longer | All |

## 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)
- [Full Skill Documentation](SKILL.md)

## Dependencies

Managed automatically by `uv`:
- fal-client
- python-dotenv
- pillow
- click
- requests

## License

This skill is part of the Claude Code skills ecosystem.

```

### _meta.json

```json
{
  "owner": "delorenj",
  "slug": "fal-text-to-image",
  "displayName": "Fal Text-to-Image",
  "latest": {
    "version": "0.1.0",
    "publishedAt": 1770396109550,
    "commit": "https://github.com/openclaw/skills/commit/a8c847de92e1a158b4a2d561d4aa0b57ad77565e"
  },
  "history": []
}

```

### references/model-comparison.md

```markdown
# fal.ai Text-to-Image Model Comparison

Detailed comparison of available text-to-image models on fal.ai platform.

## Model Benchmarks

### FLUX Series

#### flux-pro/v1.1-ultra
- **Endpoint**: `fal-ai/flux-pro/v1.1-ultra`
- **Resolution**: Up to 2K (2048x2048)
- **Strengths**: Professional-grade image quality, exceptional photo realism
- **Use Cases**: Publication-ready images, professional photography, high-res prints
- **Pricing**: Per megapixel
- **Speed**: Moderate (high quality requires more compute)
- **Best For**: Commercial projects, professional portfolios, marketing materials

#### flux-2-pro
- **Endpoint**: `fal-ai/flux-2-pro`
- **Strengths**: High-quality image manipulation, style transfer, sequential editing
- **Use Cases**: Image editing workflows, style transfer, professional edits
- **Best For**: Iterative editing, professional post-processing

#### flux-2
- **Endpoint**: `fal-ai/flux-2`
- **Strengths**: Enhanced realism, crisp text generation, native editing
- **Use Cases**: General-purpose image generation, balanced quality/speed
- **Pricing**: 100 free requests (expires Dec 25, 2025)
- **Best For**: Everyday image generation, prototyping, experimentation

#### flux-2/lora
- **Endpoint**: `fal-ai/flux-2/lora`
- **Strengths**: Custom style adaptation, fine-tuned model variations
- **Use Cases**: Domain-specific styles, personalized outputs
- **Best For**: Consistent style across generations, brand-specific imagery

#### flux-2/lora/edit
- **Endpoint**: `fal-ai/flux-2/lora/edit`
- **Strengths**: Specialized style transfer, domain-specific modifications
- **Use Cases**: Image-to-image editing with LoRA, style references
- **Best For**: Style-guided transformations, reference-based generation

#### flux/dev
- **Endpoint**: `fal-ai/flux/dev`
- **Parameters**: 12 billion
- **Architecture**: Flow transformer
- **Strengths**: High-quality text-to-image, suitable for commercial use
- **Best For**: Development and testing, personal/commercial projects

#### flux-general
- **Endpoint**: `fal-ai/flux-general`
- **Features**: LoRA, ControlNet, IP-Adapter support
- **Strengths**: Comprehensive control, multiple guidance methods
- **Best For**: Advanced users needing full control over generation

### Recraft V3

- **Endpoint**: `fal-ai/recraft/v3/text-to-image`
- **Benchmark**: SOTA in Hugging Face Text-to-Image Benchmark (Artificial Analysis)
- **Strengths**:
  - Exceptional long text generation
  - Vector art capabilities
  - Brand-style consistency
  - Industry-leading overall quality
- **Use Cases**: Typography design, logos, brand materials, posters
- **Pricing**: $0.04/image ($0.08 for vector styles)
- **Best For**: Professional design work, branding, text-heavy compositions

### Google Imagen4

#### imagen4/preview
- **Endpoint**: `fal-ai/imagen4/preview`
- **Quality**: Google's highest quality model
- **Strengths**: Overall quality, Google's latest research
- **Best For**: Users wanting Google's cutting-edge capabilities

#### imagen4/preview/fast
- **Endpoint**: `fal-ai/imagen4/preview/fast`
- **Quality**: High quality with faster generation
- **Best For**: Quick iterations with Google quality

### Stable Diffusion v3.5 Large

- **Endpoint**: `fal-ai/stable-diffusion-v35-large`
- **Architecture**: Multimodal Diffusion Transformer (MMDiT)
- **Strengths**:
  - Improved image quality
  - Exceptional typography
  - Complex prompt understanding
  - Resource-efficient
- **Best For**: Complex compositions, artistic style control

### Ideogram v2

- **Endpoint**: `fal-ai/ideogram/v2`
- **Strengths**:
  - Exceptional typography handling
  - Realistic outputs
  - Optimized for commercial use
- **Use Cases**: Posters, logos, text-heavy designs
- **Best For**: Projects where text accuracy is critical

### Bria Text-to-Image 3.2

- **Endpoint**: `fal-ai/bria/text-to-image/3.2`
- **Training Data**: Exclusively licensed data
- **Strengths**:
  - Safe for commercial use
  - Excellent text rendering
  - No copyright concerns
- **Best For**: Commercial projects with strict licensing requirements

### HiDream-I1 Series

#### hidream-i1-full
- **Endpoint**: `fal-ai/hidream-i1-full`
- **Parameters**: 17 billion
- **Quality**: State-of-the-art
- **Speed**: Seconds
- **Best For**: Maximum quality from open-source model

#### hidream-i1-dev
- **Endpoint**: `fal-ai/hidream-i1-dev`
- **Parameters**: 17 billion
- **Balance**: Quality and speed
- **Best For**: Development with high quality

#### hidream-i1-fast
- **Endpoint**: `fal-ai/hidream-i1-fast`
- **Parameters**: 17 billion
- **Steps**: 16 steps
- **Best For**: Rapid iteration and prototyping

## Selection Matrix

| Use Case | Recommended Model | Alternative |
|----------|------------------|-------------|
| Professional Photography | flux-pro/v1.1-ultra | imagen4/preview |
| Typography/Logos | recraft/v3/text-to-image | ideogram/v2 |
| General Purpose | flux-2 | flux/dev |
| Style Transfer | flux-2/lora/edit | flux-2-pro |
| Vector Art | recraft/v3/text-to-image | stable-diffusion-v35-large |
| Commercial Safe | bria/text-to-image/3.2 | flux-pro/v1.1-ultra |
| Fast Iteration | hidream-i1-fast | imagen4/preview/fast |
| Complex Prompts | stable-diffusion-v35-large | recraft/v3/text-to-image |
| Brand Consistency | flux-2/lora | recraft/v3/text-to-image |
| High-Res Outputs | flux-pro/v1.1-ultra | stable-diffusion-v35-large |

## Cost Considerations

### Free Tier Options
- **flux-2**: 100 free requests (expires Dec 25, 2025)
- Best for experimentation and prototyping

### Budget Options
- **flux/dev**: Suitable for personal and commercial use
- **stable-diffusion-v35-large**: Resource-efficient

### Premium Options
- **flux-pro/v1.1-ultra**: Per-megapixel pricing, best quality
- **recraft/v3/text-to-image**: $0.04-0.08 per image

## Performance Characteristics

### Speed Ranking (Fast to Slow)
1. hidream-i1-fast
2. imagen4/preview/fast
3. flux-2
4. flux/dev
5. stable-diffusion-v35-large
6. imagen4/preview
7. flux-pro/v1.1-ultra

### Quality Ranking (Best to Good)
1. flux-pro/v1.1-ultra
2. recraft/v3/text-to-image
3. imagen4/preview
4. hidream-i1-full
5. stable-diffusion-v35-large
6. flux-2
7. ideogram/v2

### Typography Ranking
1. recraft/v3/text-to-image
2. ideogram/v2
3. stable-diffusion-v35-large
4. bria/text-to-image/3.2
5. flux-2

## Advanced Features

### LoRA Support
- flux-2/lora
- flux-2/lora/edit
- flux-general (with LoRA tools)

### ControlNet Support
- flux-general

### IP-Adapter Support
- flux-general

### Editing Capabilities
- flux-2 (native editing)
- flux-2-pro
- flux-2/lora/edit

## Best Practices by Model

### flux-pro/v1.1-ultra
- Use for final production images
- Request specific resolutions up to 2K
- Detailed prompts yield best results
- Monitor costs (per-megapixel pricing)

### recraft/v3/text-to-image
- Specify text content clearly in prompt
- Use for brand consistency across images
- Leverage vector style for scalable outputs
- Ideal for design mockups

### flux-2
- Great starting point for most projects
- Use free tier for experimentation
- Refine prompts before moving to premium models
- Good balance of speed and quality

### flux-2/lora/edit
- Provide high-quality reference images
- Be specific about style elements to transfer
- May require iteration to match reference
- Best with similar composition to reference

### stable-diffusion-v35-large
- Use detailed, complex prompts
- Leverage artistic style keywords
- Good for creative interpretations
- Resource-efficient for batch generation

## Prompt Engineering Tips

### For Typography Models (Recraft, Ideogram)
- Explicitly state text content: "logo with text 'Company Name'"
- Specify font style: "modern sans-serif", "elegant script"
- Mention layout: "centered text", "circular arrangement"

### For Photo-Realistic Models (FLUX Pro, Imagen)
- Include lighting details: "golden hour", "studio lighting"
- Specify camera details: "50mm lens", "shallow depth of field"
- Mention style: "professional headshot", "editorial photography"

### For Style Transfer (LoRA Edit)
- Describe target content clearly
- Reference specific style elements
- May need to iterate on prompt for best match

### General Best Practices
- Be specific and descriptive
- Include desired mood/atmosphere
- Specify composition if important
- Mention any unwanted elements with negative prompts (where supported)

```

### references/usage-examples.md

```markdown
# Usage Examples

Real-world examples for common image generation tasks.

## Basic Examples

### Simple Landscape
```bash
uv run python fal-text-to-image "A serene mountain landscape at sunset with purple clouds"
```

### Portrait
```bash
uv run python fal-text-to-image "Portrait of a young woman with red hair, professional lighting"
```

### Abstract Art
```bash
uv run python fal-text-to-image "Abstract geometric patterns in blue and gold"
```

## Typography & Design

### Logo Design
```bash
uv run python fal-text-to-image \
  -m recraft/v3/text-to-image \
  "Modern tech startup logo with text 'AI Labs', minimalist design, blue and white color scheme"
```

### Poster Design
```bash
uv run python fal-text-to-image \
  -m ideogram/v2 \
  "Movie poster with text 'FUTURE CITY' in bold futuristic font, cyberpunk aesthetic"
```

### Product Label
```bash
uv run python fal-text-to-image \
  -m recraft/v3/text-to-image \
  "Coffee bag label design with text 'Morning Blend', vintage style, brown and cream colors"
```

## Professional Photography

### Corporate Headshot
```bash
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  "Professional corporate headshot of business executive, grey background, studio lighting, 50mm lens" \
  -s 2048x2048
```

### Product Photography
```bash
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  "Product photography of luxury watch on marble surface, dramatic lighting, commercial quality"
```

### Architectural Photography
```bash
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  "Modern architecture exterior, glass and steel building, golden hour lighting, wide angle"
```

## Style Transfer

### Artistic Style Transfer
```bash
uv run python fal-text-to-image \
  -m flux-2/lora/edit \
  -i van_gogh_style.jpg \
  "Cityscape at night with busy streets"
```

### Photo Style Matching
```bash
uv run python fal-text-to-image \
  -m flux-2/lora/edit \
  -i reference_photo.jpg \
  "Portrait of a man in formal attire"
```

## Creative & Artistic

### Fantasy Scene
```bash
uv run python fal-text-to-image \
  -m stable-diffusion-v35-large \
  "Dragon flying over ancient castle, dramatic clouds, fantasy art style, detailed"
```

### Sci-Fi Concept
```bash
uv run python fal-text-to-image \
  -m flux-2 \
  "Futuristic space station orbiting alien planet, cinematic lighting, concept art"
```

### Character Design
```bash
uv run python fal-text-to-image \
  -m stable-diffusion-v35-large \
  "Steampunk inventor character, full body, detailed mechanical accessories, Victorian era"
```

## Technical & Reproducible

### With Specific Seed
```bash
uv run python fal-text-to-image \
  -m flux-2 \
  --seed 42 \
  "Cyberpunk city street with neon signs"
```

### High Guidance
```bash
uv run python fal-text-to-image \
  -m flux-2 \
  --guidance 15.0 \
  "Photorealistic apple on wooden table, studio lighting"
```

### More Inference Steps
```bash
uv run python fal-text-to-image \
  -m stable-diffusion-v35-large \
  --steps 75 \
  "Highly detailed mechanical watch mechanism, macro photography"
```

### Custom Output Name
```bash
uv run python fal-text-to-image \
  -m flux-2 \
  -o company_logo_v1.png \
  "Tech company logo concept"
```

## Batch Generation Scenarios

### Testing Multiple Styles
```bash
# Version 1: Realistic
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  --seed 100 \
  -o portrait_realistic.png \
  "Portrait of young woman in garden"

# Version 2: Artistic
uv run python fal-text-to-image \
  -m stable-diffusion-v35-large \
  --seed 100 \
  -o portrait_artistic.png \
  "Portrait of young woman in garden, impressionist style"

# Version 3: Stylized
uv run python fal-text-to-image \
  -m flux-2/lora \
  --seed 100 \
  -o portrait_stylized.png \
  "Portrait of young woman in garden, anime style"
```

### Iterating on Design
```bash
# First iteration
uv run python fal-text-to-image \
  -m recraft/v3/text-to-image \
  --seed 42 \
  -o logo_v1.png \
  "Minimalist tech logo with text 'DataFlow'"

# Refine with same seed, different prompt
uv run python fal-text-to-image \
  -m recraft/v3/text-to-image \
  --seed 42 \
  -o logo_v2.png \
  "Minimalist tech logo with text 'DataFlow', blue gradient, modern sans-serif"

# Different model, same concept
uv run python fal-text-to-image \
  -m ideogram/v2 \
  --seed 42 \
  -o logo_v3.png \
  "Minimalist tech logo with text 'DataFlow', blue gradient, modern sans-serif"
```

## Commercial Use Cases

### E-Commerce Product
```bash
uv run python fal-text-to-image \
  -m bria/text-to-image/3.2 \
  "Product mockup of smartphone on clean white background, commercial photography style"
```

### Marketing Material
```bash
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  "Business team collaboration in modern office, diverse group, professional setting" \
  -s landscape_16_9
```

### Social Media Content
```bash
uv run python fal-text-to-image \
  -m flux-2 \
  "Instagram-style photo of healthy breakfast bowl, top-down view, natural lighting" \
  -s square
```

## Workflow Integration

### A/B Testing Visuals
```bash
# Test A: Traditional approach
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  --seed 999 \
  -o hero_traditional.png \
  "Professional business setting, corporate meeting"

# Test B: Modern approach
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  --seed 999 \
  -o hero_modern.png \
  "Casual collaborative workspace, startup atmosphere"
```

### Reference-Guided Iterations
```bash
# Generate base image
uv run python fal-text-to-image \
  -m flux-2 \
  -o base_concept.png \
  "Modern interior design, minimalist living room"

# Use it as reference for variations
uv run python fal-text-to-image \
  -m flux-2/lora/edit \
  -i outputs/base_concept.png \
  -o variation_1.png \
  "Modern interior with warmer tones and plants"
```

## Tips for Better Results

### Be Specific
```bash
# ❌ Vague
uv run python fal-text-to-image "a car"

# ✅ Specific
uv run python fal-text-to-image \
  "Red sports car on coastal highway, sunset lighting, cinematic angle, 4k quality"
```

### Use Technical Terms
```bash
# ❌ Generic
uv run python fal-text-to-image "nice photo of person"

# ✅ Technical
uv run python fal-text-to-image \
  -m flux-pro/v1.1-ultra \
  "Professional portrait, 85mm lens, f/1.8 aperture, studio lighting, grey backdrop"
```

### Layer Details
```bash
# ✅ Layered description
uv run python fal-text-to-image \
  "Ancient library interior | towering bookshelves | warm candlelight | dust particles in air | mysterious atmosphere | fantasy setting"
```

### Test Across Models
```bash
# Same prompt, different models
PROMPT="Vintage poster design with text 'Grand Hotel', Art Deco style"

uv run python fal-text-to-image -m recraft/v3/text-to-image "$PROMPT" -o test_recraft.png
uv run python fal-text-to-image -m ideogram/v2 "$PROMPT" -o test_ideogram.png
uv run python fal-text-to-image -m stable-diffusion-v35-large "$PROMPT" -o test_sd.png
```

```