Fal.ai Image Generation — SKILL.md

---
name: "Fal.ai Image Generation"
description: "Skill for Fal.ai Image Generation — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "content"
agents: ["claude-code", "codex", "gemini"]
tags: ["fal-ai", "content", "auto-generated"]
---

# Fal.ai Image Generation

---
name: Fal.ai Image Generation
description: Use when you need to generate high-quality AI images programmatically using Fal.ai's API. Best for applications requiring FLUX, Stable Diffusion, or other advanced image models with fast inference times.
metadata:
  author: skynet
  version: 1.0.0
category: content
---

# Fal.ai Image Generation

## Overview

Fal.ai provides serverless AI inference with focus on image generation models like FLUX, Stable Diffusion, and specialized variants. Use for production-ready image generation with predictable pricing and fast cold starts.

## Installation & Setup

### Install CLI
```bash
# Install fal CLI
pip install fal-client

# Authenticate with API key
fal auth login
# Or set environment variable
export FAL_KEY="your-api-key-here"
```

### Python Client Setup
```python
import fal_client

# Configure client
fal_client.api_key = "your-api-key"
```

## Core Workflows

### Basic Image Generation

```python
import fal_client

# FLUX.1 Schnell (fastest)
result = fal_client.subscribe(
    "fal-ai/flux/schnell",
    arguments={
        "prompt": "A serene mountain landscape at sunset",
        "image_size": "landscape_4_3",
        "num_inference_steps": 4,
        "seed": 42
    }
)

print(f"Generated image: {result['images'][0]['url']}")
```

### Advanced Generation with FLUX Pro

```python
# FLUX.1 Pro (highest quality)
result = fal_client.subscribe(
    "fal-ai/flux-pro",
    arguments={
        "prompt": "Professional headshot of a businesswoman, studio lighting, sharp focus",
        "image_size": "portrait_4_5",
        "num_inference_steps": 25,
        "guidance_scale": 3.5,
        "seed": 12345,
        "safety_tolerance": 2
    }
)

# Download image
import requests
from PIL import Image
from io import BytesIO

response = requests.get(result['images'][0]['url'])
image = Image.open(BytesIO(response.content))
image.save("generated_portrait.jpg")
```

### Batch Generation

```python
import asyncio
import fal_client

async def generate_batch():
    prompts = [
        "A cyberpunk city at night",
        "Abstract geometric patterns",
        "Vintage car in desert"
    ]
    
    tasks = []
    for prompt in prompts:
        task = fal_client.submit(
            "fal-ai/flux/schnell",
            arguments={
                "prompt": prompt,
                "image_size": "square_hd",
                "num_inference_steps": 4
            }
        )
        tasks.append(task)
    
    # Wait for all generations
    results = []
    for task in tasks:
        result = await task
        results.append(result)
    
    return results

# Run batch
results = asyncio.run(generate_batch())
```

## Model Selection Decision Tree

```
Need image generation?
├── Speed priority?
│   ├── Yes → FLUX.1 Schnell (4 steps, ~2s)
│   └── No → Continue
├── Highest quality?
│   ├── Yes → FLUX.1 Pro (25+ steps, ~15s)
│   └── No → Continue
├── Open source preference?
│   ├── Yes → FLUX.1 Dev (25+ steps, ~10s)
│   └── No → Continue
├── Specific style/model?
│   ├── Anime → flux/anime
│   ├── Realism → flux-realism
│   └── Custom → Check model catalog
```

## CLI Commands

### List Available Models
```bash
# List all models
fal models list --category image-generation

# Get model details
fal models get fal-ai/flux/schnell
```

### Generate via CLI
```bash
# Quick generation
fal run fal-ai/flux/schnell \
  --prompt "A majestic eagle soaring over mountains" \
  --image_size "landscape_4_3" \
  --output "./eagle.jpg"

# With advanced parameters
fal run fal-ai/flux-pro \
  --prompt "Portrait of a wise old wizard" \
  --image_size "portrait_4_5" \
  --num_inference_steps 30 \
  --guidance_scale 4.0 \
  --seed 777 \
  --output "./wizard.jpg"
```

### Monitor Usage
```bash
# Check current usage
fal usage

# View billing
fal billing history
```

## Image-to-Image Generation

```python
# Upload reference image
def upload_image(image_path):
    with open(image_path, "rb") as f:
        url = fal_client.upload(f, "image/jpeg")
    return url

# Image-to-image with FLUX
reference_url = upload_image("./reference.jpg")

result = fal_client.subscribe(
    "fal-ai/flux/dev/image-to-image",
    arguments={
        "prompt": "Transform into a watercolor painting",
        "image_url": reference_url,
        "strength": 0.75,
        "num_inference_steps": 28,
        "guidance_scale": 3.5
    }
)
```

## ControlNet Integration

```python
# Using ControlNet for precise control
canny_url = upload_image("./canny_edge.jpg")

result = fal_client.subscribe(
    "fal-ai/flux/dev/controlnet",
    arguments={
        "prompt": "A futuristic building with glass facade",
        "control_image_url": canny_url,
        "controlnet_conditioning_scale": 0.8,
        "num_inference_steps": 25
    }
)
```

## Configuration Parameters

### Image Sizes
```python
# Common size options
sizes = {
    "square_hd": "1024x1024",
    "square": "512x512", 
    "portrait_4_3": "768x1024",
    "portrait_16_9": "576x1024",
    "landscape_4_3": "1024x768",
    "landscape_16_9": "1024x576"
}
```

### Quality vs Speed Settings
```python
# Speed optimized
fast_config = {
    "num_inference_steps": 4,
    "guidance_scale": 0,  # CFG disabled for speed
    "model": "fal-ai/flux/schnell"
}

# Quality optimized  
quality_config = {
    "num_inference_steps": 50,
    "guidance_scale": 7.5,
    "model": "fal-ai/flux-pro"
}
```

## Error Handling

```python
import fal_client
from fal_client import ValidationError, InferenceError

try:
    result = fal_client.subscribe(
        "fal-ai/flux/schnell",
        arguments={"prompt": "test image"}
    )
except ValidationError as e:
    print(f"Invalid parameters: {e}")
except InferenceError as e:
    print(f"Generation failed: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

## Troubleshooting

### Common Issues

**"Invalid image_size parameter"**
```python
# Fix: Use valid size constants
valid_sizes = ["square_hd", "portrait_4_3", "landscape_16_9"]
# Instead of: "1024x1024"
```

**"Prompt filtered by safety system"**
```python
# Fix: Adjust safety tolerance or rephrase prompt
arguments = {
    "safety_tolerance": 3,  # More permissive (1-5)
    "prompt": "family-friendly version of prompt"
}
```

**"Rate limit exceeded"**
```python
# Fix: Implement exponential backoff
import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return fal_client.subscribe("fal-ai/flux/schnell", 
                                      arguments={"prompt": prompt})
        except Exception as e:
            if "rate limit" in str(e).lower():
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
            raise e
```

**"Model loading timeout"**
```bash
# Fix: Use pre-warmed endpoints or async submission
fal run --async fal-ai/flux/schnell --prompt "test"
```

## Performance Optimization

### Async Generation for Scale
```python
async def optimized_generation(prompts):
    # Submit all requests
    handles = []
    for prompt in prompts:
        handle = fal_client.submit_async(
            "fal-ai/flux/schnell",
            arguments={"prompt": prompt}
        )
        handles.append(handle)
    
    # Collect results as they complete
    results = []
    for handle in handles:
        result = await handle
        results.append(result)
    
    return results
```

### Cost Optimization
```python
# Choose model based on requirements
def select_model(quality_needed, speed_needed):
    if speed_needed and not quality_needed:
        return "fal-ai/flux/schnell"  # Cheapest
    elif quality_needed and not speed_needed:
        return "fal-ai/flux-pro"      # Most expensive
    else:
        return "fal-ai/flux/dev"      # Balanced
```

## Integration Examples

### Web App Integration
```python
from flask import Flask, request, jsonify
import fal_client

app = Flask(__name__)

@app.route('/generate', methods=['POST'])
def generate_image():
    prompt = request.json.get('prompt')
    
    try:
        result = fal_client.subscribe(
            "fal-ai/flux/schnell",
            arguments={"prompt": prompt}
        )
        return jsonify({
            "success": True,
            "image_url": result['images'][0]['url']
        })
    except Exception as e:
        return jsonify({
            "success": False,
            "error": str(e)
        }), 400
```

### Discord Bot Integration
```python
import discord
import fal_client

class ImageBot(discord.Client):
    async def on_message(self, message):
        if message.content.startswith('!generate '):
            prompt = message.content[10:]
            
            await message.channel.send("Generating image...")
            
            result = fal_client.subscribe(
                "fal-ai/flux/schnell",
                arguments={"prompt": prompt}
            )
            
            await message.channel.send(result['images'][0]['url'])
```