fal.ai Generate
Generate images and videos using state-of-the-art AI models on fal.ai.
Scripts
Script Purpose
generate.sh
Generate images/videos (queue-based)
upload.sh
Upload local files to fal CDN
search-models.sh
Search and discover models
get-schema.sh
Get OpenAPI schema for any model
Queue System (Default)
All requests use the queue system by default for reliability:
User Request → Queue Submit → Poll Status → Get Result ↓ request_id
Benefits:
-
Long-running tasks (video) won't timeout
-
Can check status anytime
-
Can cancel queued requests
-
Results retrievable even if connection drops
Generate Content
bash /mnt/skills/user/fal-generate/scripts/generate.sh [options]
Basic Usage (Queue Mode)
Image - submits to queue, waits for completion
bash generate.sh --prompt "A serene mountain landscape" --model "fal-ai/nano-banana-pro"
Video - same, but takes longer
bash generate.sh --prompt "Ocean waves crashing" --model "fal-ai/veo3.1"
Image-to-Video
bash generate.sh
--prompt "Camera slowly zooms in"
--model "fal-ai/kling-video/v2.6/pro/image-to-video"
--image-url "https://example.com/image.jpg"
Async Mode (Return Immediately)
For long video jobs, use --async to get request_id immediately:
Submit and return immediately
bash generate.sh --prompt "Epic battle scene" --model "fal-ai/veo3.1" --async
Output:
Request ID: abc123-def456
Request submitted. Use these commands to check:
Status: ./generate.sh --status "abc123-def456" --model "fal-ai/veo3.1"
Result: ./generate.sh --result "abc123-def456" --model "fal-ai/veo3.1"
Queue Operations
Check status
bash generate.sh --status "request_id" --model "fal-ai/veo3.1"
→ IN_QUEUE (position: 3) | IN_PROGRESS | COMPLETED
Get result (when COMPLETED)
bash generate.sh --result "request_id" --model "fal-ai/veo3.1"
Cancel (only if still queued)
bash generate.sh --cancel "request_id" --model "fal-ai/veo3.1"
Show Logs During Generation
bash generate.sh --prompt "A sunset" --model "fal-ai/nano-banana-pro" --logs
Status: IN_QUEUE (position: 2)
Status: IN_PROGRESS
> Loading model...
> Generating image...
Status: COMPLETED
File Upload
Option 1: Auto-upload with --file
Local file is automatically uploaded to fal CDN
bash generate.sh
--file "/path/to/photo.jpg"
--model "fal-ai/kling-video/v2.6/pro/image-to-video"
--prompt "Camera zooms in slowly"
Option 2: Manual upload with upload.sh
Upload first
URL=$(bash upload.sh --file "/path/to/photo.jpg")
→ https://v3.fal.media/files/xxx/photo.jpg
Then generate
bash generate.sh --image-url "$URL" --model "..." --prompt "..."
Option 3: Use existing URL
Any public URL works
bash generate.sh --image-url "https://example.com/image.jpg" ...
Supported file types:
-
Images: jpg, jpeg, png, gif, webp
-
Videos: mp4, mov, webm
-
Audio: mp3, wav, flac
Upload flow (two-step):
-
POST rest.alpha.fal.ai/storage/auth/token?storage_type=fal-cdn-v3 → {"token": "...", "base_url": "https://v3b.fal.media"}
-
POST {base_url}/files/upload Authorization: Bearer {token} → {"access_url": "https://v3b.fal.media/files/..."}
Max file size: 100MB (simple upload)
Arguments Reference
Argument Description Default
--prompt , -p
Text description (required)
--model , -m
Model ID fal-ai/nano-banana-pro
--image-url
Input image URL for I2V
--file , --image
Local file (auto-uploads)
--size
square , portrait , landscape
landscape_4_3
--num-images
Number of images 1
Mode Options:
Argument Description
(default) Queue mode - submit and poll until complete
--async
Submit to queue, return request_id immediately
--sync
Synchronous (not recommended for video)
--logs
Show generation logs while polling
Queue Operations:
Argument Description
--status ID
Check status of a queued request
--result ID
Get result of a completed request
--cancel ID
Cancel a queued request
Advanced:
Argument Description Default
--poll-interval
Seconds between status checks 2
--timeout
Max seconds to wait 600
--lifecycle N
Object expiration in seconds
--schema [MODEL]
Get OpenAPI schema
Finding Models
To discover the best and latest models, use the search API:
Search by category
bash search-models.sh --category "text-to-image" bash search-models.sh --category "text-to-video" bash search-models.sh --category "image-to-video"
Search by keyword
bash search-models.sh --query "flux" bash search-models.sh --query "kling video"
Or use the search_models MCP tool with relevant keywords.
Categories: text-to-image , image-to-image , text-to-video , image-to-video , text-to-speech , speech-to-text
Get Model Schema (OpenAPI)
IMPORTANT: Fetch schema to see exact parameters for any model.
Get schema
bash get-schema.sh --model "fal-ai/nano-banana-pro"
Show only input parameters
bash get-schema.sh --model "fal-ai/kling-video/v2.6/pro/image-to-video" --input
Quick schema via generate.sh
bash generate.sh --schema "fal-ai/veo3.1"
API Endpoint:
https://fal.ai/api/openapi/queue/openapi.json?endpoint_id={model-id}
Output
Queue Submit Response:
{ "request_id": "abc123-def456", "status": "IN_QUEUE", "response_url": "https://queue.fal.run/.../requests/abc123-def456", "status_url": "https://queue.fal.run/.../requests/abc123-def456/status", "cancel_url": "https://queue.fal.run/.../requests/abc123-def456/cancel" }
Final Result:
{ "images": [{ "url": "https://v3.fal.media/files/...", "width": 1024, "height": 768 }] }
Present Results to User
Images:
• 1024×768 | Generated in 2.2s
Videos:
Click to view video • Duration: 5s | Generated in 45s
Async Submission:
Request submitted to queue. • Request ID: abc123-def456 • Model: fal-ai/veo3 • Check status: --status "abc123-def456"
Object Lifecycle (Optional)
Control how long generated files remain accessible:
Files expire after 1 hour (3600 seconds)
bash generate.sh --prompt "..." --lifecycle 3600
Files expire after 24 hours
bash generate.sh --prompt "..." --lifecycle 86400
Troubleshooting
Timeout Error
Error: Timeout after 600s Request ID: abc123-def456
Solution: Use --status and --result to check manually, or increase --timeout .
API Key Error
Error: FAL_KEY not set
Solution: Run ./generate.sh --add-fal-key or export FAL_KEY=your_key .
Network Error (claude.ai)
Go to claude.ai/settings/capabilities and add *.fal.ai to allowed domains.