Skill: delorenj/fal-text-to-image (version 0.1.0)

--- 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**: [REDACTED_SECRET] ### **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**: [REDACTED_SECRET] ## 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**: [REDACTED_SECRET] ### **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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)