list_models
Browse and filter available Fal.ai AI models for image, video, and audio generation tasks using semantic search or category filtering.
Instructions
Discover available Fal.ai models for image, video, and audio generation. Use 'task' parameter for intelligent task-based ranking (e.g., 'portrait photography'), or 'search' for simple name/description filtering.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by category (image, video, or audio) | |
| task | No | Task description for intelligent ranking (e.g., 'anime illustration', 'product photography'). Uses Fal.ai's semantic search and prioritizes featured models. | |
| search | No | Simple search query to filter models by name or description (e.g., 'flux'). Use 'task' for better semantic matching. | |
| limit | No | Maximum number of models to return |
Implementation Reference
- Core implementation of the list_models tool handler. Retrieves models from the registry based on task, category, search, and limit parameters, handles fallback logic, and formats results as a markdown list with badges for featured models.
async def handle_list_models( arguments: Dict[str, Any], registry: ModelRegistry, ) -> List[TextContent]: """Handle the list_models tool.""" task = arguments.get("task") category = arguments.get("category") search = arguments.get("search") limit = arguments.get("limit", 20) used_fallback = False fallback_warning = "" # If task is provided, use semantic search with API if task: # Map simplified category to API category for search api_category = None if category: category_map = { "image": "text-to-image", "video": "text-to-video", "audio": "text-to-audio", } api_category = category_map.get(category) search_result = await registry.search_models( query=task, category=api_category, limit=limit ) models = search_result.models used_fallback = search_result.used_fallback if used_fallback: title = f'## Models for: "{task}" ({len(models)} found)\n' fallback_warning = f"⚠️ *Using cached results ({search_result.fallback_reason}). Results may be less relevant.*\n" subtitle = "💡 *⭐ = Featured by Fal.ai*\n" else: title = f'## Models for: "{task}" ({len(models)} found)\n' subtitle = "💡 *Sorted by relevance. ⭐ = Featured by Fal.ai*\n" else: # Standard list with optional search filter models = await registry.list_models( category=category, search=search, limit=limit ) title = f"## Available Models ({len(models)} found)\n" subtitle = "" if not models: return [ TextContent( type="text", text="No models found. Try a different category, task, or search term.", ) ] # Format output lines = [title] if fallback_warning: lines.append(fallback_warning) if subtitle: lines.append(subtitle) for model in models: # Add star badge for highlighted models highlighted_badge = " ⭐" if model.highlighted else "" lines.append(f"- `{model.id}`{highlighted_badge}") if model.name and model.name != model.id: lines.append(f" - **{model.name}**") if model.description: desc = ( model.description[:150] + "..." if len(model.description) > 150 else model.description ) lines.append(f" - {desc}") if task and model.group_label: lines.append(f" - *Family: {model.group_label}*") return [TextContent(type="text", text="\n".join(lines))] - Input schema definition for the list_models tool, including optional parameters for category, task (semantic), search, and limit.
Tool( name="list_models", description="Discover available Fal.ai models for image, video, and audio generation. Use 'task' parameter for intelligent task-based ranking (e.g., 'portrait photography'), or 'search' for simple name/description filtering.", inputSchema={ "type": "object", "properties": { "category": { "type": "string", "enum": ["image", "video", "audio"], "description": "Filter by category (image, video, or audio)", }, "task": { "type": "string", "description": "Task description for intelligent ranking (e.g., 'anime illustration', 'product photography'). Uses Fal.ai's semantic search and prioritizes featured models.", }, "search": { "type": "string", "description": "Simple search query to filter models by name or description (e.g., 'flux'). Use 'task' for better semantic matching.", }, "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100, "description": "Maximum number of models to return", }, }, "required": [], }, ), - src/fal_mcp_server/server.py:61-85 (registration)Registration of the list_models handler in the TOOL_HANDLERS dictionary used by the call_tool MCP server method to route tool calls to their implementations.
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/tools/__init__.py:14-16 (registration)Aggregation of all tool schemas (including list_models from UTILITY_TOOLS) into ALL_TOOLS list returned by the list_tools MCP server method.
ALL_TOOLS = ( UTILITY_TOOLS + IMAGE_TOOLS + IMAGE_EDITING_TOOLS + VIDEO_TOOLS + AUDIO_TOOLS ) - Import and exposure of the handle_list_models function in handlers package __init__.py for use by server modules.
from fal_mcp_server.handlers.utility_handlers import ( handle_get_pricing, handle_get_usage, handle_list_models, handle_recommend_model, handle_upload_file, )