edit_image
Modify images by describing changes in natural language. Upload an image URL and provide instructions like 'make the sky more dramatic' or 'change the car color to red' to apply AI-powered edits.
Instructions
Edit an image using natural language instructions. Describe what changes you want and the AI will apply them.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image_url | Yes | URL of the image to edit (use upload_file for local images) | |
| instruction | Yes | Natural language description of the edit (e.g., 'make the sky more dramatic', 'change the car color to red') | |
| model | No | Editing model. Options: fal-ai/flux-2/edit, fal-ai/flux-2-pro/edit (higher quality) | fal-ai/flux-2/edit |
| strength | No | How much to change the image (0=minimal, 1=maximum) | |
| seed | No | Seed for reproducible edits |
Implementation Reference
- The handler function that implements the core logic for the 'edit_image' tool. It resolves the model, prepares fal_args with image_url and instruction, executes via queue_strategy, handles errors/timeouts, extracts the output URL, and formats the response.
async def handle_edit_image( arguments: Dict[str, Any], registry: ModelRegistry, queue_strategy: QueueStrategy, ) -> List[TextContent]: """Handle the edit_image tool for natural language image editing.""" model_input = arguments.get("model", "fal-ai/flux-2/edit") try: model_id = await registry.resolve_model_id(model_input) except ValueError as e: return [ TextContent( type="text", text=f"❌ {e}. Use list_models to see available options.", ) ] fal_args: Dict[str, Any] = { "image_urls": [arguments["image_url"]], # Flux 2 Edit expects array "prompt": arguments["instruction"], } # Add optional parameters if "strength" in arguments: fal_args["strength"] = arguments["strength"] if "seed" in arguments: fal_args["seed"] = arguments["seed"] logger.info( "Starting image edit with %s: '%s'", model_id, arguments["instruction"][:50] ) try: result = await asyncio.wait_for( queue_strategy.execute_fast(model_id, fal_args), timeout=90, ) except asyncio.TimeoutError: logger.error("Image edit timed out for %s", model_id) return [ TextContent( type="text", text="❌ Image editing timed out after 90 seconds. Please try again.", ) ] except Exception as e: logger.exception("Image editing failed: %s", e) return [ TextContent( type="text", text=f"❌ Image editing failed: {e}", ) ] # Check for error in response if "error" in result: error_msg = result.get("error", "Unknown error") logger.error("Image editing failed for %s: %s", model_id, error_msg) return [ TextContent( type="text", text=f"❌ Image editing failed: {error_msg}", ) ] # Extract the result image URL - Flux 2 edit returns {"images": [{"url": "..."}]} images = result.get("images", []) if images: output_url = images[0].get("url") if isinstance(images[0], dict) else images[0] else: # Fallback to other common response formats image_data = result.get("image", {}) if isinstance(image_data, dict): output_url = image_data.get("url") else: output_url = result.get("image_url") if not output_url: logger.warning("Image edit returned no image. Result: %s", result) return [ TextContent( type="text", text="❌ Image editing completed but no image was returned.", ) ] response = "✏️ Image edited successfully!\n\n" response += f"**Instruction**: {arguments['instruction']}\n\n" response += f"**Result**: {output_url}" return [TextContent(type="text", text=response)] - The Tool schema definition for 'edit_image', including inputSchema with properties like image_url, instruction, model, strength, seed, and required fields.
Tool( name="edit_image", description="Edit an image using natural language instructions. Describe what changes you want and the AI will apply them.", inputSchema={ "type": "object", "properties": { "image_url": { "type": "string", "description": "URL of the image to edit (use upload_file for local images)", }, "instruction": { "type": "string", "description": "Natural language description of the edit (e.g., 'make the sky more dramatic', 'change the car color to red')", }, "model": { "type": "string", "default": "fal-ai/flux-2/edit", "description": "Editing model. Options: fal-ai/flux-2/edit, fal-ai/flux-2-pro/edit (higher quality)", }, "strength": { "type": "number", "default": 0.75, "minimum": 0.0, "maximum": 1.0, "description": "How much to change the image (0=minimal, 1=maximum)", }, "seed": { "type": "integer", "description": "Seed for reproducible edits", }, }, "required": ["image_url", "instruction"], }, ), - src/fal_mcp_server/server.py:61-85 (registration)The TOOL_HANDLERS dictionary that registers 'edit_image' mapped to handle_edit_image function, used by the call_tool handler to route requests.
TOOL_HANDLERS = { # Utility tools (no queue needed) "list_models": handle_list_models, "recommend_model": handle_recommend_model, "get_pricing": handle_get_pricing, "get_usage": handle_get_usage, "upload_file": handle_upload_file, # Image generation tools "generate_image": handle_generate_image, "generate_image_structured": handle_generate_image_structured, "generate_image_from_image": handle_generate_image_from_image, # Image editing tools "remove_background": handle_remove_background, "upscale_image": handle_upscale_image, "edit_image": handle_edit_image, "inpaint_image": handle_inpaint_image, "resize_image": handle_resize_image, "compose_images": handle_compose_images, # Video tools "generate_video": handle_generate_video, "generate_video_from_image": handle_generate_video_from_image, "generate_video_from_video": handle_generate_video_from_video, # Audio tools "generate_music": handle_generate_music, } - src/fal_mcp_server/server.py:20-39 (registration)Import statement in server.py that brings in the handle_edit_image handler for registration in TOOL_HANDLERS.
from fal_mcp_server.handlers import ( handle_compose_images, handle_edit_image, handle_generate_image, handle_generate_image_from_image, handle_generate_image_structured, handle_generate_music, handle_generate_video, handle_generate_video_from_image, handle_generate_video_from_video, handle_get_pricing, handle_get_usage, handle_inpaint_image, handle_list_models, handle_recommend_model, handle_remove_background, handle_resize_image, handle_upload_file, handle_upscale_image, )