fal-workflow

fal.ai Workflow Generator Generate 100% working, production-ready fal.ai workflow JSON files . Workflows chain multiple AI models together for complex generation pipelines. References: Model Reference - Detailed model configurations Common Patterns - Reusable workflow patterns Code Examples - Code snippets and partial examples Troubleshooting Reference: Complete Workflows - Working JSON examples for debugging (use ONLY when user reports errors) Core Architecture Valid Node Types ⚠️ ONLY TWO VALID NODE TYPES EXIST: Type Purpose "run" Execute a model/app "display" Output results to user ❌ INVALID: type: "input" - This does NOT exist! Input is defined ONLY in schema.input . Minimal Working Example { "name" : "my-workflow" , "title" : "My Workflow" , "contents" : { "name" : "workflow" , "nodes" : { "output" : { "type" : "display" , "id" : "output" , "depends" : [ "node-image" ] , "input" : { } , "fields" : { "image" : "$node-image.images.0.url" } } , "node-image" : { "type" : "run" , "id" : "node-image" , "depends" : [ "input" ] , "app" : "fal-ai/flux/dev" , "input" : { "prompt" : "$input.prompt" } } } , "output" : { "image" : "$node-image.images.0.url" } , "schema" : { "input" : { "prompt" : { "name" : "prompt" , "label" : "Prompt" , "type" : "string" , "required" : true , "modelId" : "node-image" } } , "output" : { "image" : { "name" : "image" , "label" : "Generated Image" , "type" : "string" } } } , "version" : "1" , "metadata" : { "input" : { "position" : { "x" : 0 , "y" : 0 } } , "description" : "Simple text to image workflow" } } , "is_public" : true , "user_id" : "" , "user_nickname" : "" , "created_at" : "" } Reference Syntax Reference Use Case Example $input.field Input value $input.prompt $node.output LLM text output $node-llm.output $node.images.0.url First image URL $node-img.images.0.url $node.image.url Single image URL $node-upscale.image.url $node.video.url Video URL $node-vid.video.url $node.audio_file.url Audio URL $node-music.audio_file.url $node.frame.url Extracted frame $node-extract.frame.url CRITICAL: No String Interpolation ⚠️ NEVER mix text with variables! Variable MUST be the ENTIRE value. // ❌ WRONG - WILL BREAK "prompt" : "Create image of $input.subject in $input.style" // ✅ CORRECT - Variable is the ENTIRE value "prompt" : "$input.prompt" "prompt" : "$node-llm.output" To combine values: Use fal-ai/text-concat or fal-ai/workflow-utilities/merge-text . See Model Reference . Critical Rules C1: Dependencies Must Match References // ❌ WRONG "node-b" : { "depends" : [ ] , "input" : { "data" : "$node-a.output" } } // ✅ CORRECT "node-b" : { "depends" : [ "node-a" ] , "input" : { "data" : "$node-a.output" } } C2: ID Must Match Object Key // ❌ WRONG "my-node" : { "id" : "different-id" } // ✅ CORRECT "my-node" : { "id" : "my-node" } C3: Use Correct LLM Type openrouter/router → Text only, no image_urls openrouter/router/vision → ONLY when analyzing images C4: Schema modelId Required "schema" : { "input" : { "field" : { "modelId" : "first-consuming-node" } } } C5: Output Depends on All Referenced Nodes "output" : { "depends" : [ "node-a" , "node-b" , "node-c" ] , "fields" : { "a" : "$node-a.video" , "b" : "$node-b.images.0.url" } } Quick Reference Card Output References Model Type Output Reference LLM $node.output Text Concat $node.results Merge Text $node.text Image Gen (array) $node.images.0.url Image Process (single) $node.image.url Video $node.video.url Music $node.audio_file.url Frame Extract $node.frame.url Use search-models.sh or search_models MCP tool to discover current models. See references/MODELS.md for workflow code templates. Input Schema "schema" : { "input" : { "text_field" : { "name" : "text_field" , "label" : "Display Label" , "type" : "string" , "description" : "Help text" , "required" : true , "modelId" : "consuming-node" } , "image_urls" : { "name" : "image_urls" , "type" : { "kind" : "list" , "elementType" : "string" } , "required" : true , "modelId" : "node-id" } } } Pre-Output Checklist Before outputting any workflow, verify: ⚠️ All nodes have type: "run" or type: "display" ONLY (NO type: "input" !) ⚠️ No string interpolation - variable MUST be ENTIRE value Every $node.xxx has matching depends entry Every node id matches object key Input schema has modelId for each field Output depends on ALL referenced nodes Correct LLM type (router vs router/vision) Usage Using Script bash /mnt/skills/user/fal-workflow/scripts/create-workflow.sh \ --name "my-workflow" \ --title "My Workflow Title" \ --nodes '[...]' \ --outputs '{...}' Using MCP Tool mcp__fal - ai__create - workflow ( { smartMode : true , intent : "Generate a story with LLM, create an illustration, then animate it" } ) Troubleshooting Invalid Node Type Error (MOST COMMON) Error: unexpected value; permitted: 'run', 'display', field required Cause: You created a node with type: "input" which does NOT exist. Solution: Remove ANY node with type: "input" . Define input fields ONLY in schema.input . Dependency Error Error: Node references $node-x but doesn't depend on it Solution: Add the referenced node to the depends array. ID Mismatch Error Error: Node key "my-node" doesn't match id "different-id" Solution: Ensure the object key matches the id field exactly. LLM Vision Error Error: image_urls provided but using text-only router Solution: Switch to openrouter/router/vision when analyzing images. Finding Model Schemas Every model's input/output schema: https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=[endpoint_id] Example: https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/nano-banana-pro