firecrawl/examples/gemini-2.5-screenshot-editor

Firecrawl + Gemini 2.5 Flash Image CLI Editor 🎨🔥

A production-ready Python CLI that combines Firecrawl's powerful screenshot capabilities with Google's Gemini 2.5 Flash Image model for advanced AI-powered image editing, artistic style transfer, and creative transformations.

🌟 Key Features

Core Capabilities

• Website Screenshot Capture: High-quality screenshots using Firecrawl API
• Text-to-Image Generation: Create images from descriptions
• Advanced Style Transfer: Van Gogh, Monet, Picasso, and 10+ artistic styles
• Multi-Image Composition: Blend multiple screenshots/images
• Iterative Refinement: Apply progressive enhancements
• Batch Processing: Process multiple URLs with same transformation
• Creative Editing: Custom AI-powered transformations

Production Features

• Robust error handling for invalid URLs, API failures, and rate limits
• Verbose mode for debugging
• Flexible output options
• Mobile and viewport-only capture modes
• Intermediate step saving for refinements

🚀 Quick Start

1. Installation

# Clone or download this example
git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl/examples/gemini-2.5-screenshot-editor

# Install dependencies
pip install -r requirements.txt

2. API Key Setup

# Copy the example env file
cp .env.example .env

# Edit .env and add your keys:
# FIRECRAWL_API_KEY=your_firecrawl_api_key
# GEMINI_API_KEY=your_gemini_api_key

Get Your API Keys:

• Firecrawl: Sign up at firecrawl.dev to get your API key
• Gemini: Get your key from Google AI Studio

3. Basic Usage

# Transform a website into Van Gogh style
python cli.py https://github.com --artistic van_gogh

# Apply cyberpunk style to any website
python cli.py https://example.com --style cyberpunk

# Generate image from text
python cli.py --generate "A futuristic dashboard with neon colors"

📚 Comprehensive Examples

🎯 Basic Argument Examples

# --edit: Custom transformation
python cli.py https://github.com --edit "Make it look like a cyberpunk interface"

# --style: Preset style
python cli.py https://stripe.com --style vintage

# --artistic: Famous art style
python cli.py https://apple.com --artistic van_gogh

# --generate: Text-to-image (no URL needed)
python cli.py --generate "Modern e-commerce website with dark theme"

# --mobile: Mobile viewport
python cli.py https://tailwindcss.com --mobile

# --viewport-only: No scrolling
python cli.py https://example.com --viewport-only

# --output: Custom filename
python cli.py https://site.com --style cyberpunk --output my_result.png

# --verbose: Debug information
python cli.py https://github.com --artistic monet --verbose

# --high-quality: Maximum quality
python cli.py https://portfolio.com --edit "Make artistic" --high-quality

# --refine: Step-by-step improvements
python cli.py https://example.com --refine "Add dark theme" "Add neon accents"

# --composite: Combine multiple sites
python cli.py https://github.com https://gitlab.com --composite "Merge these designs"

# --batch: Process multiple URLs
python cli.py --batch urls.txt --style cyberpunk

# --save-intermediates: Save each refinement step
python cli.py https://site.com --refine "Step 1" "Step 2" --save-intermediates

# --output-dir: Custom directory for outputs
python cli.py --batch urls.txt --artistic monet --output-dir art_gallery

# --preserve-content: Keep original layout
python cli.py https://apple.com --artistic van_gogh --preserve-content

# --wait: Wait before screenshot
python cli.py https://slow-site.com --wait 10 --style minimal

🎨 Artistic Style Transfer

Transform website screenshots into famous art styles:

# Van Gogh's Starry Night style
python cli.py https://github.com --artistic van_gogh --output github_van_gogh.png

# Monet's impressionist style
python cli.py https://stripe.com --artistic monet --preserve-content

# Picasso's cubist style
python cli.py https://notion.so --artistic picasso

# Andy Warhol's pop art
python cli.py https://apple.com --artistic warhol

# Japanese woodblock print
python cli.py https://tailwindcss.com --artistic ukiyo_e

Available Artistic Styles:

• van_gogh - Swirling brushstrokes, dramatic blues and yellows
• monet - Soft impressionist colors
• picasso - Cubist geometric shapes
• warhol - Pop art with bold colors
• dali - Surrealist dreamlike distortions
• ukiyo_e - Japanese woodblock print style
• watercolor - Delicate translucent painting
• oil_painting - Classical realistic textures
• pencil_sketch - Detailed pencil drawing
• comic_book - Bold outlines and vibrant colors

🔄 Iterative Refinement

Apply progressive transformations to achieve complex results:

# Multi-step enhancement (saves intermediates to current directory)
python cli.py https://example.com --refine \
  "Make it futuristic with neon glows" \
  "Add cyberpunk elements" \
  "Enhance contrast and add dramatic lighting" \
  --save-intermediates

# Save intermediates to specific directory
python cli.py https://example.com --refine \
  "Make it futuristic with neon glows" \
  "Add cyberpunk elements" \
  "Enhance contrast and add dramatic lighting" \
  --save-intermediates --output-dir refinement_steps

# Progressive style evolution
python cli.py https://github.com --refine \
  "Add vintage film grain" \
  "Apply sepia tones" \
  "Add old photograph border" \
  "Make it look 100 years old"

🎭 Multi-Image Composition

Combine multiple screenshots or images:

# Merge two website designs
python cli.py https://github.com https://gitlab.com \
  --composite "Blend these two interfaces into a unified design"

# Create a collage
python cli.py https://google.com https://bing.com https://duckduckgo.com \
  --composite "Create an artistic collage of search engines"

# Combine local images with screenshots
python cli.py https://example.com local_image.png \
  --composite "Merge website design with provided image"

📦 Batch Processing

Process multiple URLs with the same transformation:

# Create a file with URLs (one per line)
echo "https://github.com
https://gitlab.com
https://bitbucket.org" > urls.txt

# Apply same style to all
python cli.py --batch urls.txt --edit "Apply cyberpunk style"

# Batch artistic transformation
python cli.py --batch urls.txt --artistic van_gogh

🎯 Custom Creative Transformations

# Transform website into specific artistic vision
python cli.py https://github.com --edit \
  "Transform into Vincent van Gogh's Starry Night style with swirling brushstrokes"

# Creative reinterpretation
python cli.py https://apple.com --edit \
  "Reimagine as a retro 1980s computer advertisement"

# Specific style instructions
python cli.py https://notion.so --edit \
  "Convert to hand-drawn wireframe sketch with annotations"

📱 Mobile and Viewport Options

# Mobile viewport capture
python cli.py https://tailwindcss.com --mobile --style minimal

# Viewport only (no scrolling)
python cli.py https://stripe.com --viewport-only --artistic watercolor

# Full page with custom wait time
python cli.py https://github.com --wait 5 --style cyberpunk

🖼️ Pure Text-to-Image Generation

Generate images without website input:

# Website design concepts
python cli.py --generate "Modern SaaS landing page with gradients"

# With artistic style
python cli.py --generate "E-commerce homepage" --artistic van_gogh

# Creative concepts
python cli.py --generate \
  "Futuristic dashboard with holographic elements and data visualizations"

🛠️ Advanced Options

Output File Behavior

• Default: Files are saved in the current directory where the command is run
• --output: Specify exact filename and path for the final result
• --output-dir: Specify directory for batch operations or intermediate refinement steps
• --save-intermediates: When used with --refine:
  • Without --output-dir: Saves refinement_1.png, refinement_2.png, etc. in current directory
  • With --output-dir: Saves intermediate files in the specified directory

Verbose Mode

# See detailed processing information
python cli.py https://example.com --artistic van_gogh --verbose

Custom Output Paths

# Specify output file
python cli.py https://github.com --style cyberpunk --output custom_name.png

# Batch output directory
python cli.py --batch urls.txt --output-dir my_outputs

Preserve Content

# Maintain original composition in style transfer
python cli.py https://example.com --artistic van_gogh --preserve-content

📋 Full Command Reference

python cli.py [urls...] [options]

All Arguments

Argument	Type	Description	Example
urls	positional	Website URLs or image files to process	https://github.com local.png
--generate	string	Generate image from text prompt (no URL needed)	--generate "Modern dashboard design"
--style	choice	Apply preset style transformation	--style cyberpunk
--artistic	choice	Apply famous artistic style transfer	--artistic van_gogh
--edit	string	Custom editing instruction for screenshot	--edit "Make it look vintage"
--composite	string	Combine multiple images/URLs into one	--composite "Merge these designs"
--refine	list	Apply iterative refinements step by step	--refine "Add neon" "Enhance contrast"
--output, -o	path	Specify output filename	--output result.png
--output-dir	path	Directory for batch operations or intermediate refinement steps (defaults to current directory if not specified)	--output-dir results/
--batch	file	Process multiple URLs from a text file	--batch urls.txt
--compose	list	Additional images to include in composition	--compose img1.png img2.png
--mobile	flag	Capture mobile viewport	--mobile
--viewport-only	flag	Capture only visible viewport (no scrolling)	--viewport-only
--wait	int	Wait time in seconds before screenshot	--wait 5
--preserve-content	flag	Preserve original composition in style transfer	--preserve-content
--save-intermediates	flag	Save intermediate steps in refinements (saves to current dir or --output-dir if specified)	--save-intermediates
--high-quality	flag	Generate maximum quality images (default: enabled)	--high-quality
--verbose, -v	flag	Show detailed processing information	--verbose
--firecrawl-url	url	Custom Firecrawl API endpoint	--firecrawl-url https://api.custom.com

Available Preset Styles (--style)

• cyberpunk - Futuristic neon colors and glowing effects
• vintage - Sepia tones with aged, retro appearance
• artistic - Oil painting style with enhanced colors
• dramatic - High contrast cinematic look
• minimal - Clean, simplified aesthetic

Available Artistic Styles (--artistic)

• van_gogh - Starry Night swirling brushstrokes
• monet - Impressionist soft colors
• picasso - Cubist geometric shapes
• warhol - Pop art bold colors
• dali - Surrealist dreamlike distortions
• ukiyo_e - Japanese woodblock print style
• watercolor - Delicate translucent painting
• oil_painting - Classical realistic textures
• pencil_sketch - Detailed pencil drawing
• comic_book - Bold outlines and vibrant colors

🏆 Production Best Practices

Error Handling

The CLI includes comprehensive error handling for:

• Invalid URLs and network failures
• API rate limits and authentication errors
• Image processing failures
• File system permissions
• Malformed responses

Performance Optimization

• Efficient batch processing
• Proper timeout handling
• Memory-efficient image processing
• Graceful fallbacks

Code Quality

• Clean function separation
• Type hints for better IDE support
• Comprehensive docstrings
• Modular architecture

🔧 Troubleshooting

Common Issues and Solutions

Issue	Solution
"API key not found"	Check .env file has correct keys
"Screenshot failed"	Verify URL is accessible and Firecrawl has credits
"No image generated"	Try rephrasing prompt or check Gemini quota
"Style transfer failed"	Ensure image is valid and try simpler prompt

Debug Mode

# Enable verbose output for debugging
python cli.py https://example.com --verbose --artistic van_gogh

📦 Requirements

• Python 3.8+
• Active Firecrawl API key
• Active Google Gemini API key
• Internet connection

🤝 Contributing

This tool demonstrates the integration between Firecrawl and Gemini APIs. Feel free to:

• Add new artistic styles
• Implement additional features
• Improve error handling
• Enhance documentation

📄 License

MIT License - See LICENSE file for details

🎯 Use Cases

Perfect for:

• Designers: Quick mockup variations and style experiments
• Developers: Automated screenshot processing for documentation
• Marketers: Creative content generation from existing websites
• Artists: Transform web designs into artistic pieces
• Researchers: Batch process and analyze website designs

🚦 API Limits

• Firecrawl: Check your plan's screenshot limits
• Gemini: 2 QPM (queries per minute) for free tier
• Image Size: Gemini supports up to 20MB images

📞 Support

• Firecrawl Issues: firecrawl.dev/support
• Gemini Documentation: ai.google.dev
• GitHub Issues: Report bugs in the Firecrawl repository

---

Built with ❤️ for the Firecrawl community | GitHub Issue #2169