API Documentation

Complete reference for all Fal MCP Server tools available in Claude.

Available Tools

The Fal MCP Server provides 18 tools organized into five categories:

  • Image Generation (3 tools): generate_image, generate_image_structured, generate_image_from_image
  • Image Editing (6 tools): remove_background, upscale_image, edit_image, inpaint_image, resize_image, compose_images
  • Video (3 tools): generate_video, generate_video_from_image, generate_video_from_video
  • Audio (1 tool): generate_music
  • Utility (5 tools): list_models, recommend_model, get_pricing, get_usage, upload_file

Image Generation Tools

🎨 generate_image

Generate images from text descriptions using various AI models.

Parameters

Parameter Type Required Default Description
prompt string ✅ Yes - Text description of the image to generate
model string No flux_schnell Model to use for generation
negative_prompt string No - What to avoid in the image
image_size string No landscape_16_9 Aspect ratio of the image
num_images integer No 1 Number of images to generate (1-4)
seed integer No random Seed for reproducible generation

Available Models

  • flux_schnell - Fastest generation, good quality
  • flux_dev - Better quality, slower generation
  • flux_pro - Professional quality, requires Pro API
  • sdxl - Stable Diffusion XL
  • stable_diffusion - Stable Diffusion v3

Image Sizes

  • square - 1:1 aspect ratio
  • landscape_4_3 - 4:3 aspect ratio
  • landscape_16_9 - 16:9 aspect ratio (default)
  • portrait_3_4 - 3:4 aspect ratio
  • portrait_9_16 - 9:16 aspect ratio

Example Usage

1
2
3
4
5
6
7
8
9
10

{
  "tool": "generate_image",
  "arguments": {
    "prompt": "A serene mountain landscape at sunset with a lake",
    "model": "flux_dev",
    "image_size": "landscape_16_9",
    "num_images": 2,
    "negative_prompt": "people, buildings, text"
  }
}

Response

1
2
3
4

{
  "type": "text",
  "text": "🎨 Generated 2 image(s) with flux_dev:\n\nImage 1: https://fal.ai/generated/image1.jpg\nImage 2: https://fal.ai/generated/image2.jpg"
}

Image Editing Tools

✂️ remove_background

Remove the background from an image, creating a transparent PNG.

Parameters

Parameter Type Required Default Description
image_url string ✅ Yes - URL of the image to process
model string No fal-ai/birefnet/v2 Background removal model
output_format string No png Output format (png, webp)

Example Usage

1
2
3
4
5
6

{
  "tool": "remove_background",
  "arguments": {
    "image_url": "https://example.com/photo.jpg"
  }
}

🔍 upscale_image

Upscale an image to higher resolution while preserving quality.

Parameters

Parameter Type Required Default Description
image_url string ✅ Yes - URL of the image to upscale
scale integer No 2 Upscale factor (2 or 4)
model string No fal-ai/clarity-upscaler Upscaling model

Example Usage

1
2
3
4
5
6
7

{
  "tool": "upscale_image",
  "arguments": {
    "image_url": "https://example.com/lowres.jpg",
    "scale": 4
  }
}

✏️ edit_image

Edit an image using natural language instructions.

Parameters

Parameter Type Required Default Description
image_url string ✅ Yes - URL of the image to edit
instruction string ✅ Yes - Natural language edit instruction
model string No fal-ai/flux-2/edit Editing model
strength number No 0.75 Edit strength (0-1)
seed integer No random Seed for reproducible edits

Example Usage

1
2
3
4
5
6
7

{
  "tool": "edit_image",
  "arguments": {
    "image_url": "https://example.com/photo.jpg",
    "instruction": "make the sky more dramatic with orange sunset colors"
  }
}

🎭 inpaint_image

Edit specific regions of an image using a mask.

Parameters

Parameter Type Required Default Description
image_url string ✅ Yes - URL of the source image
mask_url string ✅ Yes - URL of the mask (white=edit, black=keep)
prompt string ✅ Yes - What to generate in masked area
model string No fal-ai/flux-kontext-lora/inpaint Inpainting model
negative_prompt string No - What to avoid
seed integer No random Seed for reproducibility

Example Usage

1
2
3
4
5
6
7
8

{
  "tool": "inpaint_image",
  "arguments": {
    "image_url": "https://example.com/photo.jpg",
    "mask_url": "https://example.com/mask.png",
    "prompt": "a red sports car"
  }
}

📐 resize_image

Smart resize for different social media platforms using AI outpainting.

Parameters

Parameter Type Required Default Description
image_url string ✅ Yes - URL of the source image
target_format string ✅ Yes - Platform preset or “custom”
width integer No - Custom width (if target_format=”custom”)
height integer No - Custom height (if target_format=”custom”)
mode string No extend Resize mode (extend uses AI outpainting)
background_prompt string No - Prompt for AI-generated areas

Target Formats

  • instagram_post - 1080×1080 (1:1)
  • instagram_story - 1080×1920 (9:16)
  • instagram_reel - 1080×1920 (9:16)
  • youtube_thumbnail - 1280×720 (16:9)
  • youtube_short - 1080×1920 (9:16)
  • twitter_post - 1200×675 (16:9)
  • linkedin_post - 1200×627 (1.91:1)
  • facebook_post - 1200×630 (1.91:1)
  • pinterest_pin - 1000×1500 (2:3)
  • tiktok - 1080×1920 (9:16)
  • custom - Specify width/height manually

Example Usage

1
2
3
4
5
6
7
8

{
  "tool": "resize_image",
  "arguments": {
    "image_url": "https://example.com/photo.jpg",
    "target_format": "instagram_story",
    "background_prompt": "continue the beach scenery"
  }
}

🏷️ compose_images

Overlay one image on another (e.g., add watermark, logo). Uses PIL for precise positioning.

Parameters

Parameter Type Required Default Description
base_image_url string ✅ Yes - URL of the background image
overlay_image_url string ✅ Yes - URL of the overlay image (logo, watermark)
position string No bottom-right Position preset or “custom”
x integer No - Custom X position (if position=”custom”)
y integer No - Custom Y position (if position=”custom”)
scale number No 0.15 Overlay size relative to base (0.01-1.0)
padding integer No 20 Edge padding in pixels
opacity number No 1.0 Overlay transparency (0-1)
output_format string No png Output format (png, jpeg, webp)

Position Presets

  • top-left
  • top-right
  • bottom-left
  • bottom-right (default)
  • center
  • custom (requires x, y coordinates)

Example Usage

1
2
3
4
5
6
7
8
9
10
11

{
  "tool": "compose_images",
  "arguments": {
    "base_image_url": "https://example.com/photo.jpg",
    "overlay_image_url": "https://example.com/logo.png",
    "position": "top-right",
    "scale": 0.10,
    "opacity": 0.8,
    "padding": 30
  }
}

🎬 generate_video

Transform static images into dynamic videos using AI models.

Parameters

Parameter Type Required Default Description
image_url string ✅ Yes - URL of the starting image
model string No svd Video generation model
duration integer No 4 Video duration in seconds (2-10)

Available Models

  • svd - Stable Video Diffusion (default)
  • animatediff - Fast AnimateDiff
  • kling - Kling Video model

Example Usage

1
2
3
4
5
6
7
8

{
  "tool": "generate_video",
  "arguments": {
    "image_url": "https://example.com/image.jpg",
    "model": "svd",
    "duration": 5
  }
}

Response

1
2
3
4

{
  "type": "text",
  "text": "🎬 Video generated (via queue): https://fal.ai/generated/video.mp4"
}

Processing Notes

  • Video generation uses queue API for long processing
  • Typical generation time: 30-60 seconds
  • Progress updates provided during generation
  • Maximum duration varies by model

🎵 generate_music

Generate music and audio from text descriptions.

Parameters

Parameter Type Required Default Description
prompt string ✅ Yes - Description of the music (genre, mood, instruments)
duration_seconds integer No 30 Duration in seconds (5-300)
model string No musicgen Music generation model

Available Models

  • musicgen - MusicGen Medium (default)
  • musicgen_large - MusicGen Large, higher quality

Example Usage

1
2
3
4
5
6
7
8

{
  "tool": "generate_music",
  "arguments": {
    "prompt": "Upbeat electronic dance music with synthesizers",
    "duration_seconds": 45,
    "model": "musicgen_large"
  }
}

Response

1
2
3
4

{
  "type": "text",
  "text": "🎵 Generated 45s of music (via queue): https://fal.ai/generated/audio.wav"
}

Performance Characteristics

Fast Operations (Async API)

generate_image with flux_schnell:

  • Processing time: 2-3 seconds
  • Direct async API call
  • Immediate response

Queue Operations

generate_video and generate_music:

  • Processing time: 20-60 seconds
  • Queue-based processing
  • Progress tracking available
  • Automatic retry on failure

Error Handling

The server handles various error conditions:

Authentication Errors

1
2
3
4

{
  "type": "text",
  "text": "❌ Error: FAL_KEY environment variable not set!"
}

Timeout Errors

1
2
3
4

{
  "type": "text",
  "text": "❌ Error: Timeout after 300 seconds"
}

Invalid Parameters

1
2
3
4

{
  "type": "text",
  "text": "❌ Error: Invalid model 'unknown_model'"
}

Rate Limits

Fal.ai API rate limits apply:

Tier Images/min Videos/min Audio/min
Free 10 2 5
Starter 60 10 30
Pro 300 50 100

Best Practices

1. Model Selection

  • Use flux_schnell for quick iterations
  • Use flux_dev or flux_pro for final quality
  • Choose sdxl for specific artistic styles

2. Prompt Engineering

1
2
3
4
5
6

# Good prompt
"A detailed oil painting of a mountain landscape at golden hour, 
dramatic lighting, highly detailed, artstation quality"

# Better with negative prompt
negative_prompt: "low quality, blurry, watermark, text"

3. Batch Generation

Generate multiple variations efficiently:

1
2

# Generate 4 variations with same prompt
num_images: 4

4. Seed Control

For reproducible results:

1
2

# Use fixed seed
seed: 12345

Integration Examples

Claude Desktop

In Claude, you can naturally request generation:

1
2
3
4

User: Create an image of a futuristic city

Claude: I'll generate a futuristic city image for you.
[Uses generate_image tool with appropriate parameters]

Programmatic Access

Using the MCP protocol directly:

1
2
3
4
5
6
7
8
9
10

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "generate_image",
    "arguments": {
      "prompt": "futuristic city skyline"
    }
  }
}

Transport Modes

STDIO Mode

Default mode for Claude Desktop:

  • Direct process communication
  • No network overhead
  • Fastest response time

HTTP/SSE Mode

For web integrations:

  • Server-Sent Events for streaming
  • RESTful endpoints
  • CORS support

Dual Mode

Best of both worlds:

  • STDIO for Claude Desktop
  • HTTP for web access
  • Single configuration

Troubleshooting

Common Issues

No response from tool

  • Check FAL_KEY is set correctly
  • Verify network connectivity
  • Check server logs for errors

Slow generation

  • Normal for video/music (20-60s)
  • Check Fal.ai service status
  • Consider using faster models

Quality issues

  • Improve prompt specificity
  • Use negative prompts
  • Try different models

API Changelog

v0.4.0 (Latest)

  • Added Docker support
  • HTTP/SSE transport mode
  • Dual transport mode

v0.3.0

  • Native async API integration
  • Queue management improvements
  • Better error handling

v0.2.0

  • Added music generation
  • Extended video duration support
  • Performance optimizations

v0.1.0

  • Initial release
  • Basic image and video generation
  • STDIO transport only
← Installation Examples →