Agent skill
fal-generate
Generate images and videos using fal.ai AI models with queue support. Use when the user requests "Generate image", "Create video", "Make a picture of...", "Text to image", "Image to video", "Search models", or similar generation tasks.
Install this agent skill to your Project
npx add-skill https://github.com/fal-ai-community/skills/tree/main/skills/claude.ai/fal-generate
Metadata
Additional technical details for this skill
- author
- fal-ai
- version
- 3.0.0
SKILL.md
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):
1. POST rest.alpha.fal.ai/storage/auth/token?storage_type=fal-cdn-v3
→ {"token": "...", "base_url": "https://v3b.fal.media"}
2. 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](https://v3.fal.media/files/.../video.mp4)
• 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.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
fal-ai-community/skills
fal-image-edit
Edit images using AI on fal.ai. Style transfer, object removal, background changes, and more. Use when the user requests "Edit image", "Remove object", "Change background", "Apply style", or similar image editing tasks.
fal-ai-community/skills
fal-lip-sync
Create talking head videos, lip sync audio to video, and animate portraits with expressions. Use when the user requests "Talking head", "Lip sync", "Make this person talk", "Animate portrait", "Live portrait", "Avatar video".
fal-ai-community/skills
fal-workflow
Generate production-ready fal.ai workflow JSON files. Use when user requests "create workflow", "chain models", "multi-step generation", "image to video pipeline", or complex AI generation pipelines.
fal-ai-community/skills
fal-restore
Restore and fix image quality — deblur, denoise, dehaze, fix faces, restore documents. Use when the user requests "Fix blurry image", "Remove noise", "Fix face", "Restore photo", "Enhance document", "Deblur", "Denoise".
fal-ai-community/skills
fal-platform
fal.ai Platform APIs for model management, pricing, usage tracking, and cost estimation. Use when user asks "show pricing", "check usage", "estimate cost", "setup fal", "add API key", or platform management tasks.
fal-ai-community/skills
fal-vision
Analyze images using AI — segment objects, detect objects, extract text (OCR), describe images, ask questions about images. Use when the user requests "Segment image", "Detect objects", "OCR", "Extract text from image", "Describe image", "What's in this image", "Image analysis".
Didn't find tool you were looking for?