fal.ai Model API Skill

Run 600+ generative AI models on fal.ai.

Arguments

• Command:

  $0

  (search | schema | run | status | result | upload)
• Arg 1:

  $1

  (model_id, search query, or file path)
• Arg 2+:

  $2

  ,

  $3

  , etc. (additional parameters)
• All args:

  $ARGUMENTS

Session Output

Save generated files to session folder:

mkdir -p ~/.fal/sessions/${CLAUDE_SESSION_ID}

Downloaded images/videos go to:

~/.fal/sessions/${CLAUDE_SESSION_ID}/

---

Authentication

Requires

FAL_KEY

environment variable. If requests fail with 401, tell user:

Get an API key from https://fal.ai/dashboard/keys
Then: export FAL_KEY="your-key-here"

---

Command:

$0

If $0 = "search"

Search for models matching

$1

:

curl -s "https://api.fal.ai/v1/models?q=$1&limit=15" \
  -H "Authorization: Key $FAL_KEY" | jq -r '.models[] | "• \(.endpoint_id) — \(.metadata.display_name) [\(.metadata.category)]"'

For category search, use:

curl -s "https://api.fal.ai/v1/models?category=$1&limit=15" \
  -H "Authorization: Key $FAL_KEY" | jq -r '.models[] | "• \(.endpoint_id) — \(.metadata.display_name)"'

Categories:

text-to-image

,

image-to-video

,

text-to-video

,

image-to-3d

,

training

,

speech-to-text

,

text-to-speech

---

If $0 = "schema"

Get input schema for model

$1

:

curl -s "https://api.fal.ai/v1/models?endpoint_id=$1&expand=openapi-3.0" \
  -H "Authorization: Key $FAL_KEY" | jq '.models[0].openapi.components.schemas.Input.properties'

Show required vs optional fields to help user understand what inputs are needed.

---

If $0 = "run"

Run model

$1

with parameters from remaining arguments.

Step 1: Parse parameters Extract

--key value

pairs from

$ARGUMENTS

after the model_id to build JSON payload.

Example:

/fal run fal-ai/flux-2 --prompt "a cat" --image_size landscape_16_9

→ Model:

fal-ai/flux-2

→ Payload:

{"prompt": "a cat", "image_size": "landscape_16_9"}

Step 2: Submit to queue

curl -s -X POST "https://queue.fal.run/$1" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '<JSON_PAYLOAD>'

Step 3: Poll until complete

# Get request_id from response, then poll:
while true; do
  STATUS=$(curl -s "https://queue.fal.run/$1/requests/$REQUEST_ID/status" \
    -H "Authorization: Key $FAL_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "COMPLETED" ]; then break; fi
  if [ "$STATUS" = "FAILED" ]; then echo "Job failed"; break; fi
  sleep 3
done

Step 4: Get result and save

# Fetch result
RESULT=$(curl -s "https://queue.fal.run/$1/requests/$REQUEST_ID" \
  -H "Authorization: Key $FAL_KEY")

# Create session output folder
mkdir -p ~/.fal/sessions/${CLAUDE_SESSION_ID}

# Download images/videos
# For images: jq -r '.images[0].url' and curl to download
# Save as: ~/.fal/sessions/${CLAUDE_SESSION_ID}/<timestamp>_<model>.png

---

If $0 = "status"

Check status of request

$2

for model

$1

:

curl -s "https://queue.fal.run/$1/requests/$2/status?logs=1" \
  -H "Authorization: Key $FAL_KEY" | jq '{status: .status, queue_position: .queue_position, logs: .logs}'

---

If $0 = "result"

Get result of completed request

$2

for model

$1

:

curl -s "https://queue.fal.run/$1/requests/$2" \
  -H "Authorization: Key $FAL_KEY" | jq '.'

---

If $0 = "upload"

Upload file

$1

to fal CDN:

curl -s -X POST "https://fal.run/fal-ai/storage/upload" \
  -H "Authorization: Key $FAL_KEY" \
  -F "file=@$1"

Returns URL to use in model requests.

---

Quick Reference

Popular models:

• fal-ai/flux-2

  — Fast text-to-image

• fal-ai/flux-2-pro

  — High quality text-to-image

• fal-ai/kling-video/v2/image-to-video

  — Image to video

• fal-ai/minimax/video-01/image-to-video

  — Image to video

• fal-ai/whisper

  — Speech to text

Common parameters for text-to-image:

• --prompt "description"

  — What to generate

• --image_size landscape_16_9

  — Aspect ratio (square, portrait_4_3, landscape_16_9)

• --num_images 1

  — Number of images

Example invocations:

• /fal search video

  — Find video models

• /fal schema fal-ai/flux-2

  — See input options

• /fal run fal-ai/flux-2 --prompt "a sunset over mountains"

• /fal status fal-ai/flux-2 abc-123

• /fal upload ./photo.png