fal-workflow

If you were dispatched as a subagent to execute a specific task, skip this skill.

fal.ai Workflow Generator

Generate 100% working, production-ready fal.ai workflow JSON files. Workflows chain multiple AI models together for complex generation pipelines.

Model Discovery: Use bash skills/fal/scripts/search.sh and bash skills/fal/scripts/schema.sh to discover current models and their parameters dynamically. Do not hardcode model IDs.

---

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. Use bash skills/fal/scripts/schema.sh --model "fal-ai/text-concat" --input to see exact parameters.

---

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 bash skills/fal/scripts/search.sh --query "model name" to discover current models, or bash skills/fal/scripts/schema.sh --model "fal-ai/model-id" for exact parameters.

---

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

The agent constructs workflow JSON files directly, following all the rules and schema definitions in this skill. No scripts or MCP tools are needed — author the JSON inline according to the Core Architecture and Critical Rules sections above.

---

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

Or use: bash skills/fal/scripts/schema.sh --model "fal-ai/model-id"