fal

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

fal Skill

Intent-first workflow for fal.ai: discover models, probe cheaply, refine from feedback, execute with cost awareness. All API calls go through bash scripts — you provide the workflow intelligence.

Prerequisites

• bash (any modern version)
• curl (HTTP client)
• jq (JSON processor)
• FAL_KEY environment variable (get one at https://fal.ai/dashboard/keys)

Workflow

digraph fal_workflow {
    "Intent" [shape=doublecircle];
    "Discover candidates" [shape=box];
    "Check pricing" [shape=box];
    "Probe (cheap sample)" [shape=box];
    "Review probe?" [shape=diamond];
    "Refine with feedback" [shape=box];
    "Final execution" [shape=box];
    "Result" [shape=doublecircle];

    "Intent" -> "Discover candidates";
    "Discover candidates" -> "Check pricing";
    "Check pricing" -> "Probe (cheap sample)";
    "Probe (cheap sample)" -> "Review probe?";
    "Review probe?" -> "Refine with feedback" [label="needs work"];
    "Review probe?" -> "Final execution" [label="looks good"];
    "Refine with feedback" -> "Probe (cheap sample)";
    "Final execution" -> "Result";
}

Script Reference

The session-start hook injects the full script path into your context. Use it as shown. If the path was not injected, resolve it from the plugin root: <plugin_root>/skills/fal/scripts/<name>.sh.

Script	Purpose	Key Flags
search.sh	Discover models	--query, --category, --limit
schema.sh	Model input/output schema	--model, --input
pricing.sh	Price lookup	--model (repeatable)
run.sh	Sync execution	--model, --prompt, --file, --set K=V
queue.sh	Async jobs	subcommands: submit, status, result, cancel, wait
upload.sh	File upload to CDN	--file
docs.sh	Documentation search	--query, --limit

All scripts support --json for raw JSON output and --help for usage.

---

WORKFLOW INSTRUCTIONS

NEVER execute a model without the user explicitly choosing it. Always present model options with pricing and wait for the user to pick. The only exception is if the user names a specific model in their request.

These rules encode the workflow intelligence. Follow them for every fal.ai task.

Step 1: Classify the Task

Identify the user's intent and map it to a model category.

User intent contains	Category	Search flags
"generate image", "photo", "illustration", "draw"	text-to-image	--category text-to-image
"video from image", file + "animate", "bring to life"	image-to-video	--category image-to-video
"generate video", "clip", "video of"	text-to-video	--category text-to-video
"edit image", "style transfer", "remove bg", "upscale"	image-to-image	--category image-to-image
"speech", "voice", "read aloud", "TTS"	text-to-speech	--category text-to-speech
"transcribe", "speech to text", "STT"	speech-to-text	--category speech-to-text
"music", "audio generation", "sound"	text-to-music	--category text-to-music
"3D model", "mesh", "point cloud"	text-to-3d	--category text-to-3d
"train", "fine-tune", "lora"	training	--query "training lora"

Step 2: Discover Models and Present Options

HARD RULE: Never pick a model automatically. Always present options and let the user choose.

Discover candidates:

bash skills/fal/scripts/search.sh --category "text-to-image" --limit 5

Then fetch pricing for the top candidates:

bash skills/fal/scripts/pricing.sh --model "fal-ai/flux-2" --model "fal-ai/flux-2-pro" --model "fal-ai/recraft-v3"

Present the options to the user with pricing:

Here are the available models for text-to-image:

1. fal-ai/flux-2 — $0.012/megapixel
2. fal-ai/flux-2-pro — $0.05/megapixel
3. fal-ai/recraft-v3 — $0.02/megapixel

Which one would you like to use?

Only proceed after the user picks a model. If the user specifies a model upfront (e.g., "use flux"), skip discovery and confirm: "I'll use fal-ai/flux-2, correct?"

Cost awareness: When presenting model options, always include pricing. Flag models that cost > $0.10/image or > $0.50/second of video as expensive.

Step 3: Probe (Cheap Sample)

After the user picks a model, run a low-cost sample to validate the approach.

Probe reduction rules — always apply these for probes:

• Set num_images=1 (never generate multiple images in a probe)
• Set duration to minimum (e.g., 3s for video)
• Set resolution to minimum (e.g., 720p, or square image size)
• Halve num_inference_steps if the parameter exists
• Use --set to apply reductions:

bash skills/fal/scripts/run.sh --model "fal-ai/flux/dev" \
    --prompt "a sunset over mountains" \
    --set num_images=1 --set image_size=square

Step 4: Review and Refine

Present the probe result to the user and wait for feedback. Based on their response:

• If satisfied → proceed to Step 5 (final execution)
• If they want adjustments (prompt, style, settings) → apply changes and re-probe (repeat Step 3)
• If they want a different model → go back to Step 2 and present options again
• If they want to stop → stop

This is a loop. Repeat as many times as the user needs until they're happy with the result or decide to move on.

Step 5: Final Execution

Run with full quality settings:

bash skills/fal/scripts/run.sh --model "fal-ai/flux/dev" \
    --prompt "a sunset over mountains, cinematic lighting" \
    --set num_images=4 --set image_size=landscape_16_9

Async Detection

Use queue.sh instead of run.sh for:

• Video generation (typically takes 30s-5min)
• Training/fine-tuning jobs
• Any task where the model's typical execution time exceeds ~30 seconds

# Submit async job
bash skills/fal/scripts/queue.sh submit --model "fal-ai/kling-video/v2.6/pro/text-to-video" \
    --prompt "cinematic sunset timelapse" --set duration=5

# Wait for completion (with timeout)
bash skills/fal/scripts/queue.sh wait --model "fal-ai/kling-video/v2.6/pro/text-to-video" \
    --request-id "REQUEST_ID" --timeout 300

---

Common Patterns

Generate an image

bash skills/fal/scripts/search.sh --query "flux" --category "text-to-image" --limit 3
bash skills/fal/scripts/run.sh --model "fal-ai/flux/dev" --prompt "a serene mountain landscape at sunset"

Image-to-video (with file upload)

bash skills/fal/scripts/search.sh --category "image-to-video" --limit 3
bash skills/fal/scripts/queue.sh submit --model "fal-ai/kling-video/v2.6/pro/image-to-video" \
    --file ./photo.jpg --prompt "slow cinematic zoom"

Text-to-speech

bash skills/fal/scripts/search.sh --query "speech" --category "text-to-speech" --limit 3
bash skills/fal/scripts/run.sh --model "fal-ai/f5-tts" --prompt "Hello world, this is a test."

Transcribe audio

bash skills/fal/scripts/run.sh --model "fal-ai/whisper" --file ./recording.mp3

Compare pricing before deciding

bash skills/fal/scripts/pricing.sh --model "fal-ai/flux/dev" --model "fal-ai/flux-pro" --model "fal-ai/flux/schnell"

Check model schema to find exact parameters

bash skills/fal/scripts/schema.sh --model "fal-ai/flux/dev" --input

Search documentation

bash skills/fal/scripts/docs.sh --query "flux lora training"

Upload a file manually

bash skills/fal/scripts/upload.sh --file ./photo.jpg
# Returns: https://v3.fal.media/files/.../photo.jpg

---

Output Presentation

Images: Display as markdown image links with dimensions.

![Generated Image](https://v3.fal.media/files/...)
1024x768 | Model: fal-ai/flux/dev

Videos: Display as clickable links with duration.

[View video](https://v3.fal.media/files/.../video.mp4)
Duration: 5s | Model: fal-ai/kling-video/v2.6/pro

Audio: Display as clickable links.

[Listen to audio](https://v3.fal.media/files/.../audio.mp3)
Model: fal-ai/f5-tts

Async jobs: Display request ID and follow-up commands.

Job submitted.
Request ID: abc123-def456
Check: bash skills/fal/scripts/queue.sh status --model "..." --request-id "abc123-def456"
Wait:  bash skills/fal/scripts/queue.sh wait --model "..." --request-id "abc123-def456"

---

Multi-Model Pipelines

For chaining multiple models into a workflow (e.g., generate image -> animate -> add audio), use the fal-ai:fal-workflow skill instead. It handles structured JSON pipeline authoring with validation rules.