Skip to content
fal.ai genmedia CLI

fal.ai genmedia CLI Skill

Foundational fal.ai skill that drives the genmedia CLI across 1200+ hosted generative model endpoints — smart routing, schema inspection, async queues and agent-parseable JSON.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from fal-ai-community/skills.

$ npx skills add fal-ai-community/skills --skill genmedia

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/genmedia/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/fal-ai-community/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/genmedia ~/.claude/skills/genmedia

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/genmedia/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Search, inspect, run and manage 1200+ fal.ai model endpoints from one CLI
  • Smart routing: `genmedia run "<prompt>"` classifies the prompt and picks a default endpoint per modality
  • Schema inspection before running so custom parameters do not fail with 422
  • `--json` output mode designed for agents to parse
  • `--async` queue plus status polling for long-running video, audio and 3D jobs
  • `--download` handles auth, naming and file-format detection instead of raw curl

genmedia is the agent-first CLI for fal.ai, and this skill is the foundation of the fal.ai community skill collection — every other skill in that repository (cinematography, character design, commercial, UGC, storytelling, game assets, 3D) executes its work by calling genmedia rather than wrapping the fal.ai HTTP API directly.

The skill exists because a catalogue of 1200+ endpoints is exactly the situation where an agent will confidently invent a model ID. Its rules are written to prevent that:

  1. Always pass `--json` when an agent will read the output; pretty mode is for humans.
  2. Prefer smart routing. genmedia run "<prompt>" with no endpoint classifies the prompt and routes to a sensible per-modality default. Explicit endpoint discovery is reserved for when the user names a model, wants a specific style or quality tier, or the default is wrong.
  3. Never invent endpoint IDs. Discover with genmedia models "<query>", which auto-filters by inferred modality, and verify with genmedia models --endpoint_id <id>.
  4. Inspect the schema before custom parameters. genmedia schema <endpoint_id> --json returns exact field names; guessing flags fails with a 422.
  5. Save with `--download`, not curl — the CLI handles authentication, naming and format detection.
  6. Use `--async` for long jobs. Image work usually completes inline; video, audio and 3D need queue submission plus status polling.

Setup needs an API key from the fal.ai dashboard and the genmedia CLI from fal-ai-community/genmedia-cli. Running genmedia init installs the default skill bundle into .agents/skills/ or .claude/skills/. A references/full-reference.md file in the skill carries the complete flag-by-flag command surface. MIT licensed.

Best for anyone building generative-media pipelines — batch product photography, ad variants, storyboards, lipsync — who wants an agent to pick and drive hosted models reliably instead of hand-writing API calls. Note this is a community-maintained repository rather than a first-party fal.ai product, and it bills against your own fal.ai account.

Try it

Once installed, ask your agent something like:

Find a fal.ai text-to-video endpoint that supports audio, check its schema, and queue a 10-second clip of a product rotating on a plinth.

SKILL.md

The instructions your agent loads, as published by fal.ai community.

SKILL.md
name
genmedia
description
Use the genmedia CLI to search, inspect, run, and manage 1200+ fal.ai model endpoints. Trigger when the user mentions "genmedia", "fal CLI", or asks to "search models", "run a model", "fetch schema", "check pricing", "upload to fal", "queue async job", "track request", or any direct interaction with the fal.ai endpoint catalog. This is the foundational skill. Every other fal.ai-related skill in this repo executes its work through genmedia commands. Use `--json` whenever the output will be parsed by an agent.

genmedia CLI: fal.ai endpoint runner

genmedia is the agent-first CLI for fal.ai. It works in a terminal for humans (pretty output) and equally well for agents (structured JSON when piped or with --json). All other skills in this repo call genmedia for execution, they do not wrap the fal.ai HTTP API directly.

For the full command surface (every flag, every option, every example), see [references/full-reference.md](references/full-reference.md).

Critical rules
  1. Always use `--json` when an agent will read the output. Pretty mode is for humans only.
  2. Prefer smart routing for default-quality requests. genmedia run "<prompt>" (no endpoint, no --prompt needed) classifies the prompt and routes to a sensible default per modality. Only do explicit endpoint discovery when the user names a model, asks for a non-default behavior (specific style, quality tier, parameter), or the smart-route default is wrong for the task.
  3. Never invent endpoint IDs. When you do need a specific endpoint, use genmedia models "<query>" to discover (auto-filters by inferred modality) and genmedia models --endpoint_id <id> to verify.
  4. Inspect schema before running with custom params. genmedia schema <endpoint_id> --json shows the exact field names. Smart routing only needs prompt; explicit endpoints with custom params need a schema check first or guessed flags fail with 422.
  5. Save files with `--download`, not curl. The CLI handles authentication, naming, and file format detection.
  6. Use `--async` for long-running generation. Image work usually completes inline; video/audio/3D usually need queue + status polling.
Command index
CommandPurpose
genmedia setupConfigure API key, output mode, auto-update
genmedia models <query>Search the catalog (or --category, or --endpoint_id)
genmedia schema <endpoint_id>Inspect inputs/outputs (compact or --format openapi)
genmedia run <endpoint_id> --<param> <value>Execute a model
genmedia status <endpoint_id> <request_id>Poll an async job (with --result, --logs, --cancel, --download)
genmedia upload <path-or-url>Upload a local file or remote URL to the fal.ai CDN
genmedia pricing <endpoint_id>Check cost per call
genmedia docs <query>Search fal.ai documentation
genmedia initInstall the default skill bundle into .agents/skills/ or .claude/skills/
`genmedia skills <listinstall
genmedia version / genmedia updateCheck or apply CLI updates
Quick patterns
Smart routing (preferred for default-quality requests)

The CLI classifies the prompt by modality (image / video / music / tts / 3d) and picks a sensible default endpoint. The output includes a routed block so you can verify which endpoint actually ran.

genmedia run "a cat on the moon" --json
genmedia run "a 5-second clip of a robot dancing" --json
genmedia run "narrate this paragraph in a calm voice" --json

Override anytime with an explicit endpoint id (positional that contains /):

genmedia run fal-ai/flux/pro --prompt "a cat on the moon" --json
Discover when the user names a fuzzy task or wants a specific endpoint

genmedia models "<query>" auto-applies --category from the same classifier the smart router uses, so the result list is focused on the right modality. Pass --no-classify to disable, or --category <cat> to override.

genmedia models "background removal product image" --json
genmedia models --category text-to-video --limit 5 --json
genmedia models "video models with character consistency" --no-classify --json
genmedia docs "webhook callbacks" --json
Run a specific model and download the result
genmedia run fal-ai/flux/dev \
 --prompt "a cat on the moon" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json
Async + poll
SUBMIT=$(genmedia run fal-ai/veo3.1 --prompt "a dog running" --async --json)
REQ=$(echo "$SUBMIT" | jq -r '.request_id')
genmedia status fal-ai/veo3.1 "$REQ" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json

Smart routing also works for async — the response includes routed and endpoint_id so you know which endpoint to poll on status:

SUBMIT=$(genmedia run "a 30-second video of waves" --async --json)
REQ=$(echo "$SUBMIT" | jq -r '.request_id')
EP=$(echo "$SUBMIT" | jq -r '.endpoint_id')
genmedia status "$EP" "$REQ" --download "./out/" --json
Upload then run
URL=$(genmedia upload ./photo.jpg --json | jq -r '.url')
genmedia run fal-ai/nano-banana-pro/edit \
 --image_urls "$URL" \
 --prompt "make the sky stormy" \
 --download "./out/{request_id}_{index}.{ext}" \
 --json
Setup (first-time only)

If genmedia is not installed:

curl https://genmedia.sh/install -fsS | bash # Linux / macOS
irm https://genmedia.sh/install.ps1 | iex # Windows PowerShell
genmedia setup --non-interactive --api-key "$FAL_KEY"

For full setup details (output modes, auto-update, .env loading) see [full-reference.md](references/full-reference.md).

Install
New

Higgsfield's official skill for generating images, video, 3D assets and audio from an agent through the higgsfield CLI, plus Marketing Studio ad videos and Virality Predictor scoring of finished creatives.

Replicate's official skill for running models via its API — predictions, polling, Prefer: wait, webhooks with signature validation, streaming and file handling.

Browse all skills →