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

bash /mnt/skills/user/fal-generate/scripts/generate.sh [options]

Basic Usage (Queue Mode)

bash

# 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:

bash

# 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

bash

# 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

bash generate.sh --prompt "A sunset" --model "fal-ai/flux/dev" --logs
# Status: IN_QUEUE (position: 2)
# Status: IN_PROGRESS
#   > Loading model...
#   > Generating image...
# Status: COMPLETED

File Upload

Option 1: Auto-upload with --file

bash

# 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

bash

# 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

bash

# 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/flux/dev`
`--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	-

Recommended Models

Text-to-Image

Model	Notes
`fal-ai/nano-banana-pro`	Best overall - T2I and editing
`fal-ai/flux-2-turbo`	Open source, high quality
`fal-ai/flux-2-klein-9b`	Open source, fast
`fal-ai/flux/dev`	Good balance (default)
`fal-ai/flux/schnell`	~1 second
`fal-ai/ideogram/v3`	Best for text rendering

Text-to-Video

Model	Notes
`fal-ai/veo3.1`	High quality
`fal-ai/bytedance/seedance/v1/pro`	Fast, good quality
`fal-ai/sora-2/pro`	OpenAI Sora
`fal-ai/kling-video/v2.5-turbo/pro`	Fast, reliable
`fal-ai/minimax/hailuo-02/pro`	Good for characters

Image-to-Video

Model	Notes
`fal-ai/kling-video/v2.6/pro/image-to-video`	Best overall
`fal-ai/veo3/fast`	Fast, high quality
`fal-ai/bytedance/seedance/v1.5/pro/image-to-video`	Smooth motion
`fal-ai/minimax/hailuo-02/standard/image-to-video`	Good balance

Search Models

bash

# Search by keyword
bash search-models.sh --query "flux"

# Filter by category
bash search-models.sh --category "text-to-video"

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.

bash

# 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:

json

{
  "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:

json

{
  "images": [{ "url": "https://v3.fal.media/files/...", "width": 1024, "height": 768 }]
}

Present Results to User

Images:

![Generated Image](https://v3.fal.media/files/...)
• 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:

bash

# 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

export FAL_KEY=your_key

Network Error (claude.ai)

Go to

claude.ai/settings/capabilities

and add

*.fal.ai

to allowed domains.

fal-generate

NPX Install

SKILL.md Content

fal.ai Generate

Scripts

Queue System (Default)

Generate Content

Basic Usage (Queue Mode)

Async Mode (Return Immediately)

Queue Operations

Show Logs During Generation

File Upload

Option 1: Auto-upload with --file

Option 2: Manual upload with upload.sh

Option 3: Use existing URL

Arguments Reference

Recommended Models

Text-to-Image

Text-to-Video

Image-to-Video

Search Models

Get Model Schema (OpenAPI)

Output

Present Results to User

Object Lifecycle (Optional)

Troubleshooting

Timeout Error

API Key Error

Network Error (claude.ai)