Fal.Ai Media Generation#

Generate images, videos, and transcripts using fal.ai's API with support for FLUX, Stable Diffusion, Whisper, and more.

Features#

• Queue-based async generation (submit → poll → result)
• Support for 600+ AI models
• Image generation (FLUX, SDXL, Recraft)
• Video generation (MiniMax, WAN)
• Speech-to-text (Whisper)
• Robust error handling with clear messages
• Stdlib-only dependencies (no external packages)

Setup#

1. Get your API key from https://fal.ai/dashboard/keys
2. Configure with:

bash

export FAL_KEY="your-api-key"

Or via clawdbot config:

bash

clawdbot config set skill.fal_api.key YOUR_API_KEY

Usage#

Interactive Mode#

text

You: Generate a cyberpunk cityscape with FLUX
clawd: Creates the image and returns the URL

CLI#

bash

# Basic image generation
python3 fal_api.py --prompt "A cyberpunk cityscape" --model flux-schnell

# High-quality with custom settings
python3 fal_api.py --prompt "A sunset over mountains" --model flux-dev \
    --guidance-scale 5.0 --steps 20

# Reproducible (same seed = same image)
python3 fal_api.py --prompt "A robot" --seed 12345

# List available models
python3 fal_api.py --list-models

Python Script#

python

from fal_api import FalAPI

api = FalAPI()

# Generate and wait
urls = api.generate_and_wait(
    prompt="A serene Japanese garden",
    model="flux-dev"
)
print(urls)

Available Models#

ModelEndpointTypeflux-schnellfal-ai/flux/schnellImage (fast)flux-devfal-ai/flux/devImageflux-profal-ai/flux-pro/v1.1-ultraImage (2K)fast-sdxlfal-ai/fast-sdxlImagerecraft-v3fal-ai/recraft-v3Imagesd35-largefal-ai/stable-diffusion-v35-largeImageminimax-videofal-ai/minimax-video/image-to-videoVideowan-videofal-ai/wan/v2.1/1.3b/text-to-videoVideowhisperfal-ai/whisperAudio

For the full list, run:

bash

python3 fal_api.py --list-models

Parameters#

ParameterTypeDefaultDescriptionpromptstrrequiredImage/video descriptionmodelstr"flux-dev"Model name from table aboveimage_sizestr"landscape_16_9"Preset: square, portrait_4_3, landscape_16_9, etc.num_imagesint1Number of images to generateseedintNoneRandom seed for reproducibilityguidance_scalefloatNoneCFG scale (how closely to follow prompt)num_inference_stepsintNoneInference steps (higher = more detail, slower)stepsintNoneCLI alias for num_inference_steps

CLI Examples#

bash

# Basic image
python fal_api.py --prompt "A sunset over mountains" --model flux-schnell

# High-quality with custom settings
python fal_api.py --prompt "A cyberpunk city" --model flux-dev \
    --guidance-scale 5.0 --steps 20

# Reproducible (same seed = same image)
python fal_api.py --prompt "A robot" --seed 12345

Error Handling#

The skill provides clear error messages for common issues:

• 401 Unauthorized → Invalid API key
• 429 Rate Limit → Wait and retry
• 402 Payment Required → Insufficient credits

Requirements#

• Python 3.7+
• No external dependencies (uses stdlib only)