fal-ai/minimax/image-01 MCP Server

A Model Context Protocol (MCP) server that provides access to the fal-ai/minimax/image-01 image generation model. This server allows you to generate high-quality images using MiniMax (Hailuo AI) Text to Image technology through the fal.ai platform.

Features

• High-Quality Image Generation: Generate stunning images using the fal-ai/minimax/image-01 model

• MiniMax (Hailuo AI) Technology: Advanced text-to-image generation with excellent quality

• Multiple Generation Methods: Support for synchronous and queue-based generation

• Flexible Aspect Ratios: Support for various aspect ratios from square to panoramic

• Prompt Optimization: Optional prompt enhancement for better results

• Local Image Download: Automatically downloads generated images to local storage

• Queue Management: Submit long-running requests and check their status

• Webhook Support: Optional webhook notifications for completed requests

• Stylized and Realistic Output: Supports both stylized and photorealistic image generation

Installation

1. Clone this repository:

2. Install dependencies:

3. Build the project:

Configuration

Environment Variables

Set your fal.ai API key as an environment variable:

You can get your API key from fal.ai.

MCP Client Configuration

Add this server to your MCP client configuration. For example, in Claude Desktop's config file:

If the package is published to npm, you can use:

Alternatively, if you've cloned the repository locally:

Available Tools

1. minimax_generate

Generate images using the standard synchronous method.

Parameters:

• prompt (required): Text prompt for image generation (max 1500 characters). Longer text prompts will result in better quality images.

• aspect_ratio (optional): Aspect ratio of the generated image (default: "1:1")

• num_images (optional): Number of images to generate (1-9, default: 1)

• prompt_optimizer (optional): Whether to enable automatic prompt optimization (default: false)

Example:

2. minimax_generate_queue

Submit a long-running image generation request to the queue.

Parameters: Same as minimax_generate plus:

• webhook_url (optional): URL for webhook notifications

Returns: A request ID for tracking the job

3. minimax_queue_status

Check the status of a queued request.

Parameters:

• request_id (required): The request ID from queue submission

• logs (optional): Include logs in response (default: true)

4. minimax_queue_result

Get the result of a completed queued request.

Parameters:

• request_id (required): The request ID from queue submission

API Information

• Endpoint: https://fal.run/fal-ai/minimax/image-01

• Model ID: fal-ai/minimax/image-01

• Category: text-to-image

• Kind: inference

• Tags: stylized, realism

Aspect Ratios

The MiniMax model supports the following aspect ratios:

• 1:1: Square format (default)

• 16:9: Widescreen landscape

• 4:3: Standard landscape

• 3:2: Classic photo landscape

• 2:3: Classic photo portrait

• 3:4: Standard portrait

• 9:16: Vertical/mobile format

• 21:9: Ultra-wide panoramic

Example:

Prompt Optimization

Enable prompt optimization to enhance your text prompts for better results:

When enabled, the AI will automatically improve your prompt to generate higher quality images. This is disabled by default.

Output

Generated images are automatically downloaded to a local images/ directory with descriptive filenames. The response includes:

• Local file paths

• Original URLs

• Image dimensions (when available)

• Content types

• File sizes

• Generation parameters used

• Request IDs for tracking

Error Handling

The server provides detailed error messages for:

• Missing API keys

• Invalid parameters

• Network issues

• API rate limits

• Generation failures

• Prompt length violations (max 1500 characters)

Development

Running in Development Mode

Testing the Server

Getting the Installation Path

API Reference

This server implements the fal-ai/minimax/image-01 API. For detailed API documentation, visit:

• fal.ai Model Playground

• fal.ai API Documentation

• fal.ai Client Library

Examples

Basic Text-to-Image Generation

Photorealistic Portrait

Landscape Image with Optimization

Multiple Images Generation

Ultra-wide Panoramic Scene

Queue-based Generation with Webhook

Tips for Better Results

1. Use Detailed Prompts: Longer, more descriptive prompts generally produce better quality images

2. Enable Prompt Optimization: Use prompt_optimizer: true for enhanced results

3. Choose Appropriate Aspect Ratios: Match the aspect ratio to your intended use case

4. Be Specific: Include details about style, lighting, composition, and quality level

5. Use Style Keywords: Terms like "photorealistic", "cinematic", "detailed", "high resolution" can improve output

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

Support

For issues and questions:

• Open an issue on GitHub

• Check the fal.ai documentation

Changelog

v1.0.0

• Initial release with fal-ai/minimax/image-01 API support

• MiniMax (Hailuo AI) Text to Image generation with superior capabilities

• Support for multiple aspect ratios (1:1 to 21:9)

• Prompt optimization for enhanced results (disabled by default)

• Queue management with webhook support

• Local image download functionality

• Support for generating up to 9 images per request

• Comprehensive error handling

• Updated API schema matching latest fal.ai specifications