/fal-workflow

name: fal-workflow
description: Author and execute multi-step media pipelines on fal.ai. Two modes: (A) declarative workflow JSON files for the fal.ai workflow runtime ("create workflow", "chain models", "image to video pipeline"); (B) imperative genmedia CLI orchestration when scripting locally ("design pipeline", "fan-out generation", "frame bridging", "narrated video", "dataset generation").
metadata:
 author: fal-ai
 version: "4.0.0"

fal.ai Workflows: Two Modes

> **Runtime:** Two modes. Mode A authors `.json` files for the fal.ai workflow runtime (executed in the cloud, no local CLI needed). Mode B drives the [genmedia CLI](https://github.com/fal-ai-community/genmedia-cli) for local orchestration. See the `genmedia` skill for Mode B command syntax; run `genmedia init` once if not yet installed.

This skill covers two complementary ways to build multi-step media pipelines on fal.ai. They share endpoints and concepts but differ in deliverable.

| Mode | Deliverable | When to use | |------|-------------|-------------| | **A. Workflow JSON** | A portable `.json` file the fal.ai workflow runtime executes | The user wants a reusable, shareable workflow asset; the pipeline graph is fixed at design time | | **B. genmedia CLI orchestration** | A sequence of `genmedia run / status / upload` calls (often scripted) | Local scripting, exploratory pipelines, dataset jobs, branching logic, or pipelines that need conditional steps |

If unsure: prefer Mode A when the result is a deliverable for someone else to run; Mode B when you are running it yourself or steps need runtime decisions.

---

Mode A: Workflow JSON authoring

Generate **100% working, production-ready fal.ai workflow JSON files**. Workflows chain multiple AI models together via a declarative graph.

**JSON-mode references:**

• [MODELS.md](references/MODELS.md), model configurations for JSON nodes
• [PATTERNS.md](references/PATTERNS.md), reusable JSON workflow patterns
• [EXAMPLES.md](references/EXAMPLES.md), code snippets and partial examples
• [WORKFLOWS.md](references/WORKFLOWS.md), full JSON workflows (debugging reference; use only when user reports errors)

Mode B: genmedia CLI orchestration

Plan and execute a sequence of `genmedia` calls with clear inputs, outputs, dependencies, and quality checks. Use this when a single model call is not enough and the orchestration happens in your shell, not on fal.ai.

**CLI-mode references:**

• [pipeline-patterns.md](references/pipeline-patterns.md), fan-out, sequential composition, frame bridging, multi-modal assembly, variation matrices
• [node-rules.md](references/node-rules.md), per-role rules (planner / generator / editor / utility / QA / manifest)
• [utility-endpoints.md](references/utility-endpoints.md), utility endpoint catalog (resize, composite, mask, audio, subtitle, etc.)
• [recipes.md](references/recipes.md), end-to-end recipes (cinematic video, product campaign, character continuity, narrated documentary, dataset, social batch)

For default endpoint choices in Mode B, consult `fal-models-catalog`. Always run `genmedia schema <endpoint_id> --json` before executing and `genmedia pricing <endpoint_id> --json` when cost matters.

---

Mode A: Workflow JSON authoring (continued)

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](references/MODELS.md#text-utilities-critical-for-combining-values).

---

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_url