fal-workflow

fal.ai 工作流生成器

生成 100% 可运行、可用于生产环境的 fal.ai 工作流 JSON 文件。工作流将多个 AI 模型串联起来，构建复杂的生成流水线。

参考资料：

• 模型参考 - 详细的模型配置
• 常见模式 - 可复用的工作流模式
• 代码示例 - 代码片段和部分示例

故障排除参考：

• 完整工作流 - 用于调试的可运行 JSON 示例（仅在用户报告错误时使用）

---

核心架构

有效节点类型

⚠️ 仅有两种有效的节点类型：

类型	用途
"run"	执行模型／应用
"display"	向用户输出结果

❌ 无效： type: "input" - 该类型并不存在！输入仅在 schema.input 中定义。

最小可运行示例

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

引用语法

引用	使用场景	示例
$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

关键：禁止字符串插值

⚠️ 绝不可将文本与变量混用！变量必须是整个值。

// ❌ 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"

合并值： 使用 fal-ai/text-concat 或 fal-ai/workflow-utilities/merge-text。请参阅模型参考。

---

关键规则

C1：依赖项必须与引用匹配

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

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

C2：ID 必须与对象键匹配

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

// ✅ CORRECT
"my-node": { "id": "my-node" }

C3：使用正确的 LLM 类型

• openrouter/router → 仅处理文本，不支持 image_urls
• openrouter/router/vision → 仅在分析图片时使用

C4：Schema 必须包含 modelId

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

C5：输出取决于所有被引用的节点

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

---

---

快速参考卡

输出引用

模型类型	输出引用
LLM	$node.output
Text Concat	$node.results
Merge Text	$node.text
图像生成（数组）	$node.images.0.url
图像处理（单张）	$node.image.url
视频	$node.video.url
音乐	$node.audio_file.url
帧提取	$node.frame.url

使用 search-models.sh 或 search_models MCP 工具来查找当前模型。请参阅 references/MODELS.md 中的工作流代码模板。

---

输入 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"
    }
  }
}

---

输出前检查清单

输出任何工作流前，请确认：

• ⚠️ 所有节点的类型都只能是 type: "run" 或 type: "display"（不能有 type: "input"！）
• ⚠️ 没有字符串插值——变量必须是整个值
• 每个 $node.xxx 都有对应的 depends 条目
• 每个节点的 id 都与对象键匹配
• 输入 Schema 的每个字段都有 modelId
• 输出依赖于所有被引用的节点
• LLM 类型正确（router 或 router/vision）

---

用法

使用脚本

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

使用 MCP 工具

mcp__fal-ai__create-workflow({
  smartMode: true,
  intent: "Generate a story with LLM, create an illustration, then animate it"
})

---

故障排除

无效节点类型错误（最常见）

Error: unexpected value; permitted: 'run', 'display', field required

**原因：**你创建了一个 type: "input" 节点，但该类型并不存在。 **解决方案：**移除所有 type: "input" 节点。输入字段只能在 schema.input 中定义。

依赖项错误

Error: Node references $node-x but doesn't depend on it

**解决方案：**将被引用的节点添加到 depends 数组中。

ID 不匹配错误

Error: Node key "my-node" doesn't match id "different-id"

**解决方案：**确保对象键与 id 字段完全匹配。

LLM 视觉错误

Error: image_urls provided but using text-only router

**解决方案：**分析图片时，切换到 openrouter/router/vision。

---

查找模型 Schema

每个模型的输入／输出 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