fal.ai Model API Skill
Run 1000+ 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-imagefal-ai/flux-2-pro
— High quality text-to-imagefal-ai/kling-video/v2/image-to-video
— Image to videofal-ai/minimax/video-01/image-to-video
— Image to videofal-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
