generate_image_structured
Generate images with structured prompts for precise control over composition, style, lighting, and subjects, enabling AI agents to create detailed visual content.
Instructions
Generate images with detailed structured prompts for precise control over composition, style, lighting, and subjects. Ideal for AI agents that need fine-grained control.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scene | Yes | Overall scene description - the main subject and setting | |
| subjects | No | List of subjects with their positions and descriptions | |
| style | No | Art style (e.g., 'Digital art painting', 'Photorealistic', 'Watercolor', 'Oil painting') | |
| color_palette | No | Hex color codes for the palette (e.g., ['#000033', '#6A0DAD', '#FFFFFF']) | |
| lighting | No | Lighting description (e.g., 'Soft golden hour lighting', 'Dramatic chiaroscuro') | |
| mood | No | Emotional mood of the image (e.g., 'Serene', 'Dramatic', 'Mysterious') | |
| background | No | Background description | |
| composition | No | Compositional rules (e.g., 'Rule of thirds', 'Centered', 'Golden ratio') | |
| camera | No | Camera settings for photographic style control | |
| effects | No | Visual effects (e.g., ['Bokeh', 'Light rays', 'Lens flare', 'Motion blur']) | |
| negative_prompt | No | What to avoid in the image (e.g., 'blurry, low quality, distorted') | |
| model | No | Model ID or alias. Use list_models to see options. | flux_schnell |
| image_size | No | landscape_16_9 | |
| num_images | No | ||
| seed | No | Seed for reproducible generation | |
| enable_safety_checker | No | Enable safety checker to filter inappropriate content | |
| output_format | No | Output image format | png |
Implementation Reference
- The core handler function that implements the generate_image_structured tool logic. Constructs a structured JSON prompt from the input parameters (scene, subjects, style, etc.) and generates images using the Fal.ai model registry and queue strategy.
async def handle_generate_image_structured( arguments: Dict[str, Any], registry: ModelRegistry, queue_strategy: QueueStrategy, ) -> List[TextContent]: """Handle the generate_image_structured tool.""" model_input = arguments.get("model", "flux_schnell") 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.", ) ] # Build structured JSON prompt from arguments structured_prompt: Dict[str, Any] = {} # Required field structured_prompt["scene"] = arguments["scene"] # Optional structured fields for field in [ "subjects", "style", "color_palette", "lighting", "mood", "background", "composition", "camera", "effects", ]: if field in arguments: structured_prompt[field] = arguments[field] # Convert structured prompt to JSON string json_prompt = json.dumps(structured_prompt, indent=2) fal_args: Dict[str, Any] = { "prompt": json_prompt, "image_size": arguments.get("image_size", "landscape_16_9"), "num_images": arguments.get("num_images", 1), } # Add optional generation parameters if "negative_prompt" in arguments: fal_args["negative_prompt"] = arguments["negative_prompt"] if "seed" in arguments: fal_args["seed"] = arguments["seed"] if "enable_safety_checker" in arguments: fal_args["enable_safety_checker"] = arguments["enable_safety_checker"] if "output_format" in arguments: fal_args["output_format"] = arguments["output_format"] # Use fast execution with timeout protection logger.info("Starting structured image generation with %s", model_id) try: result = await asyncio.wait_for( queue_strategy.execute_fast(model_id, fal_args), timeout=60, ) except asyncio.TimeoutError: logger.error("Structured image generation timed out for %s", model_id) return [ TextContent( type="text", text=f"❌ Image generation timed out after 60 seconds with {model_id}. Please try again.", ) ] # Check for error in response if "error" in result: error_msg = result.get("error", "Unknown error") logger.error( "Structured image generation failed for %s: %s", model_id, error_msg ) return [ TextContent( type="text", text=f"❌ Image generation failed: {error_msg}", ) ] images = result.get("images", []) if not images: logger.warning( "Structured image generation returned no images. Model: %s", model_id, ) return [ TextContent( type="text", text=f"❌ No images were generated by {model_id}. The prompt may have been filtered or the request format was invalid.", ) ] # Extract URLs safely try: urls = [img["url"] for img in images] except (KeyError, TypeError) as e: logger.error("Malformed image response from %s: %s", model_id, e) return [ TextContent( type="text", text=f"❌ Image generation completed but response was malformed: {e}", ) ] response = ( f"🎨 Generated {len(urls)} image(s) with {model_id} (structured prompt):\n\n" ) for i, url in enumerate(urls, 1): response += f"Image {i}: {url}\n" return [TextContent(type="text", text=response)] - The input schema and Tool definition for generate_image_structured, providing detailed structured input parameters for precise image generation control including subjects, camera settings, effects, and more.
Tool( name="generate_image_structured", description="Generate images with detailed structured prompts for precise control over composition, style, lighting, and subjects. Ideal for AI agents that need fine-grained control.", inputSchema={ "type": "object", "properties": { "scene": { "type": "string", "description": "Overall scene description - the main subject and setting", }, "subjects": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of subject (e.g., 'person', 'building', 'animal')", }, "description": { "type": "string", "description": "Detailed description of the subject", }, "pose": { "type": "string", "description": "Pose or action of the subject", }, "position": { "type": "string", "enum": ["foreground", "midground", "background"], "description": "Position in the composition", }, }, }, "description": "List of subjects with their positions and descriptions", }, "style": { "type": "string", "description": "Art style (e.g., 'Digital art painting', 'Photorealistic', 'Watercolor', 'Oil painting')", }, "color_palette": { "type": "array", "items": {"type": "string"}, "description": "Hex color codes for the palette (e.g., ['#000033', '#6A0DAD', '#FFFFFF'])", }, "lighting": { "type": "string", "description": "Lighting description (e.g., 'Soft golden hour lighting', 'Dramatic chiaroscuro')", }, "mood": { "type": "string", "description": "Emotional mood of the image (e.g., 'Serene', 'Dramatic', 'Mysterious')", }, "background": { "type": "string", "description": "Background description", }, "composition": { "type": "string", "description": "Compositional rules (e.g., 'Rule of thirds', 'Centered', 'Golden ratio')", }, "camera": { "type": "object", "properties": { "angle": { "type": "string", "description": "Camera angle (e.g., 'Low angle', 'Eye level', 'Bird's eye')", }, "distance": { "type": "string", "description": "Shot distance (e.g., 'Close-up', 'Medium shot', 'Wide shot')", }, "focus": { "type": "string", "description": "Focus description (e.g., 'Sharp focus on subject, blurred background')", }, "lens": { "type": "string", "description": "Lens type (e.g., 'Wide-angle', '50mm portrait', 'Telephoto')", }, "f_number": { "type": "string", "description": "Aperture (e.g., 'f/1.8', 'f/5.6', 'f/11')", }, "iso": { "type": "integer", "description": "ISO setting (e.g., 100, 400, 800)", }, }, "description": "Camera settings for photographic style control", }, "effects": { "type": "array", "items": {"type": "string"}, "description": "Visual effects (e.g., ['Bokeh', 'Light rays', 'Lens flare', 'Motion blur'])", }, "negative_prompt": { "type": "string", "description": "What to avoid in the image (e.g., 'blurry, low quality, distorted')", }, "model": { "type": "string", "default": "flux_schnell", "description": "Model ID or alias. Use list_models to see options.", }, "image_size": { "type": "string", "enum": [ "square", "landscape_4_3", "landscape_16_9", "portrait_3_4", "portrait_9_16", ], "default": "landscape_16_9", }, "num_images": { "type": "integer", "default": 1, "minimum": 1, "maximum": 4, }, "seed": { "type": "integer", "description": "Seed for reproducible generation", }, "enable_safety_checker": { "type": "boolean", "default": True, "description": "Enable safety checker to filter inappropriate content", }, "output_format": { "type": "string", "enum": ["jpeg", "png", "webp"], "default": "png", "description": "Output image format", }, }, "required": ["scene"], }, ), - src/fal_mcp_server/server.py:61-85 (registration)Registration of the generate_image_structured handler in the TOOL_HANDLERS dictionary, mapping the tool name to its handler function for execution in the MCP server.
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/handlers/image_handlers.py:19-22 (registration)No, wrong. Wait, this is import in server.py actually. For handlers __init__.py
arguments: Dict[str, Any], registry: ModelRegistry, queue_strategy: QueueStrategy, ) -> List[TextContent]: - src/fal_mcp_server/handlers/__init__.py:18-22 (registration)Export/import of the handler function in the handlers package __init__.py, making it available for server imports.
from fal_mcp_server.handlers.image_handlers import ( handle_generate_image, handle_generate_image_from_image, handle_generate_image_structured, )