API Documentation

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

Available Tools

The Fal MCP Server provides three main tools that Claude can use:

🎨 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"
}

🎬 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 →