Back to Details

fal-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

fal.ai Workflow Generator

fal.ai 工作流生成器

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)
生成100%可运行、适用于生产环境的fal.ai工作流JSON文件。工作流可将多个AI模型链式组合，构建复杂的生成流水线。
参考资料：
  • 模型参考 - 详细的模型配置
  • 通用模式 - 可复用的工作流模式
  • 代码示例 - 代码片段和部分示例
故障排除参考：
  • 完整工作流 - 用于调试的可运行JSON示例（仅在用户报告错误时使用）

Core Architecture

核心架构

Valid Node Types

有效节点类型

⚠️ ONLY TWO VALID NODE TYPES EXIST:
TypePurpose
"run"
Execute a model/app
"display"
Output results to user
❌ INVALID: 
type: "input"
- This does NOT exist! Input is defined ONLY in 
schema.input
.
⚠️ 仅存在两种有效节点类型：
类型用途
"run"
执行模型/应用
"display"
向用户输出结果
❌ 无效： 
type: "input"
- 该类型不存在！输入仅能在
schema.input
中定义。

Minimal Working Example

最小可运行示例

json
{
  "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": ""
}
json
{
  "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

引用语法

ReferenceUse CaseExample
$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
引用方式使用场景示例
$input.field
输入值
$input.prompt
$node.output
LLM文本输出
$node-llm.output
$node.images.0.url
第一张图片URL
$node-img.images.0.url
$node.image.url
单张图片URL
$node-upscale.image.url
$node.video.url
视频URL
$node-vid.video.url
$node.audio_file.url
音频URL
$node-music.audio_file.url
$node.frame.url
提取的帧
$node-extract.frame.url

CRITICAL: No String Interpolation

重要提示：禁止字符串插值

⚠️ NEVER mix text with variables! Variable MUST be the ENTIRE value.
json
// ❌ 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.
⚠️ 切勿将文本与变量混合！变量必须是整个值。
json
// ❌ 错误 - 会导致故障
"prompt": "Create image of $input.subject in $input.style"

// ✅ 正确 - 变量是整个值
"prompt": "$input.prompt"
"prompt": "$node-llm.output"
如需合并值： 使用
fal-ai/text-concat
或
fal-ai/workflow-utilities/merge-text
。请查看模型参考。

Critical Rules

关键规则

C1: Dependencies Must Match References

C1：依赖必须与引用匹配

json
// ❌ WRONG
"node-b": {
  "depends": [],
  "input": { "data": "$node-a.output" }
}

// ✅ CORRECT
"node-b": {
  "depends": ["node-a"],
  "input": { "data": "$node-a.output" }
}
json
// ❌ 错误
"node-b": {
  "depends": [],
  "input": { "data": "$node-a.output" }
}

// ✅ 正确
"node-b": {
  "depends": ["node-a"],
  "input": { "data": "$node-a.output" }
}

C2: ID Must Match Object Key

C2：ID必须与对象键匹配

json
// ❌ WRONG
"my-node": { "id": "different-id" }

// ✅ CORRECT
"my-node": { "id": "my-node" }
json
// ❌ 错误
"my-node": { "id": "different-id" }

// ✅ 正确
"my-node": { "id": "my-node" }

C3: Use Correct LLM Type

C3：使用正确的LLM类型

  • openrouter/router
    → Text only, no image_urls
  • openrouter/router/vision
    → ONLY when analyzing images
  • openrouter/router
    → 仅支持文本，不支持image_urls
  • openrouter/router/vision
    → 仅在分析图片时使用

C4: Schema modelId Required

C4：Schema必须包含modelId

json
"schema": {
  "input": {
    "field": { "modelId": "first-consuming-node" }
  }
}
json
"schema": {
  "input": {
    "field": { "modelId": "first-consuming-node" }
  }
}

C5: Output Depends on All Referenced Nodes

C5：输出依赖所有引用的节点

json
"output": {
  "depends": ["node-a", "node-b", "node-c"],
  "fields": {
    "a": "$node-a.video",
    "b": "$node-b.images.0.url"
  }
}
json
"output": {
  "depends": ["node-a", "node-b", "node-c"],
  "fields": {
    "a": "$node-a.video",
    "b": "$node-b.images.0.url"
  }
}

Default Models

默认模型

TaskDefault Model
Image generation
fal-ai/nano-banana-pro
Image editing
fal-ai/nano-banana-pro/edit
Video (I2V)
fal-ai/bytedance/seedance/v1.5/pro/image-to-video
Text LLM
openrouter/router
with 
google/gemini-2.5-flash
Vision LLM
openrouter/router/vision
with 
google/gemini-3-pro-preview
Music
fal-ai/elevenlabs/music
Upscale
fal-ai/seedvr/upscale/image
Text concat (2 texts)
fal-ai/text-concat
Text merge (array)
fal-ai/workflow-utilities/merge-text
Video merge
fal-ai/ffmpeg-api/merge-videos
Audio+Video merge
fal-ai/ffmpeg-api/merge-audio-video
Frame extract
fal-ai/ffmpeg-api/extract-frame
任务默认模型
图片生成
fal-ai/nano-banana-pro
图片编辑
fal-ai/nano-banana-pro/edit
视频（图片转视频）
fal-ai/bytedance/seedance/v1.5/pro/image-to-video
文本LLM
openrouter/router
搭配 
google/gemini-2.5-flash
视觉LLM
openrouter/router/vision
搭配 
google/gemini-3-pro-preview
音乐生成
fal-ai/elevenlabs/music
图片放大
fal-ai/seedvr/upscale/image
文本拼接（2段文本）
fal-ai/text-concat
文本合并（数组）
fal-ai/workflow-utilities/merge-text
视频合并
fal-ai/ffmpeg-api/merge-videos
音视频合并
fal-ai/ffmpeg-api/merge-audio-video
帧提取
fal-ai/ffmpeg-api/extract-frame

Quick Reference Card

快速参考卡片

Output References

输出引用

Model TypeOutput 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
模型类型输出引用方式
LLM
$node.output
文本拼接
$node.results
文本合并
$node.text
图片生成（数组）
$node.images.0.url
图片处理（单张）
$node.image.url
视频
$node.video.url
音乐
$node.audio_file.url
帧提取
$node.frame.url

Common App IDs

常用应用ID

fal-ai/nano-banana-pro
fal-ai/nano-banana-pro/edit
fal-ai/text-concat
fal-ai/workflow-utilities/merge-text
fal-ai/bytedance/seedance/v1.5/pro/image-to-video
fal-ai/kling-video/o1/image-to-video
fal-ai/kling-video/v2.6/pro/image-to-video
fal-ai/elevenlabs/music
fal-ai/ffmpeg-api/merge-videos
fal-ai/ffmpeg-api/merge-audio-video
fal-ai/ffmpeg-api/extract-frame
fal-ai/seedvr/upscale/image
openrouter/router
openrouter/router/vision
fal-ai/nano-banana-pro
fal-ai/nano-banana-pro/edit
fal-ai/text-concat
fal-ai/workflow-utilities/merge-text
fal-ai/bytedance/seedance/v1.5/pro/image-to-video
fal-ai/kling-video/o1/image-to-video
fal-ai/kling-video/v2.6/pro/image-to-video
fal-ai/elevenlabs/music
fal-ai/ffmpeg-api/merge-videos
fal-ai/ffmpeg-api/merge-audio-video
fal-ai/ffmpeg-api/extract-frame
fal-ai/seedvr/upscale/image
openrouter/router
openrouter/router/vision

Input Schema

输入Schema

json
"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"
    }
  }
}
json
"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)
在输出任何工作流之前，请验证：
  • ⚠️ 所有节点仅使用
    type: "run"
    或
    type: "display"
    （禁止使用
    type: "input"
    ！）
  • ⚠️ 无字符串插值 - 变量必须是整个值
  • 每个
    $node.xxx
    都有对应的
    depends
    条目
  • 每个节点的
    id
    与对象键匹配
  • 输入Schema的每个字段都有
    modelId
  • 输出依赖所有引用的节点
  • 使用正确的LLM类型（router vs router/vision）

Usage

使用方法

Using Script

使用脚本

bash
bash /mnt/skills/user/fal-workflow/scripts/create-workflow.sh \
  --name "my-workflow" \
  --title "My Workflow Title" \
  --nodes '[...]' \
  --outputs '{...}'
bash
bash /mnt/skills/user/fal-workflow/scripts/create-workflow.sh \
  --name "my-workflow" \
  --title "My Workflow Title" \
  --nodes '[...]' \
  --outputs '{...}'

Using MCP Tool

使用MCP工具

javascript
mcp__fal-ai__create-workflow({
  smartMode: true,
  intent: "Generate a story with LLM, create an illustration, then animate it"
})
javascript
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
.
Error: unexpected value; permitted: 'run', 'display', field required
原因： 创建了包含
type: "input"
的节点，该类型不存在。 解决方案： 删除所有
type: "input"
的节点。仅在
schema.input
中定义输入字段。

Dependency Error

依赖错误

Error: Node references $node-x but doesn't depend on it
Solution: Add the referenced node to the 
depends
array.
Error: Node references $node-x but doesn't depend on it
解决方案： 将引用的节点添加到
depends
数组中。

ID Mismatch Error

ID不匹配错误

Error: Node key "my-node" doesn't match id "different-id"
Solution: Ensure the object key matches the 
id
field exactly.
Error: Node key "my-node" doesn't match id "different-id"
解决方案： 确保对象键与
id
字段完全匹配。

LLM Vision Error

LLM视觉错误

Error: image_urls provided but using text-only router
Solution: Switch to 
openrouter/router/vision
when analyzing images.
Error: image_urls provided but using text-only router
解决方案： 在分析图片时切换为
openrouter/router/vision
。

Finding Model Schemas

查找模型Schema

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
每个模型的输入/输出Schema：
https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=[endpoint_id]
示例：
https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/nano-banana-pro