dvcrn 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