fal.ai Integration

Generate and edit images via fal.ai's queue-based API.

Setup

Add your API key to

TOOLS.md

### fal.ai
FAL_KEY: your-key-here

Get a key at: https://fal.ai/dashboard/keys

The script checks (in order):

FAL_KEY

env var →

TOOLS.md

Supported Models

fal-ai/nano-banana-pro (Text → Image)

Google's Gemini 3 Pro for text-to-image generation.

input_data = {
    "prompt": "A cat astronaut on the moon",      # required
    "aspect_ratio": "1:1",                        # auto|21:9|16:9|3:2|4:3|5:4|1:1|4:5|3:4|2:3|9:16
    "resolution": "1K",                           # 1K|2K|4K
    "output_format": "png",                       # jpeg|png|webp
    "safety_tolerance": "4"                       # 1 (strict) to 6 (permissive)
}

fal-ai/nano-banana-pro/edit (Image → Image)

Gemini 3 Pro for image editing. Slower (~20s) but handles complex edits well.

input_data = {
    "prompt": "Transform into anime style",       # required
    "image_urls": [image_data_uri],               # required - array of URLs or base64 data URIs
    "aspect_ratio": "auto",
    "resolution": "1K",
    "output_format": "png"
}

fal-ai/flux/dev/image-to-image (Image → Image)

FLUX.1 dev model. Faster (~2-3s) for style transfers.

input_data = {
    "prompt": "Anime style portrait",             # required
    "image_url": image_data_uri,                  # required - single URL or base64 data URI
    "strength": 0.85,                             # 0-1, higher = more change
    "num_inference_steps": 40,
    "guidance_scale": 7.5,
    "output_format": "png"
}

fal-ai/kling-video/o3/pro/video-to-video/edit (Video → Video)

Kling O3 Pro for video transformation with AI effects.

Limits:

Formats: .mp4, .mov only
Duration: 3-10 seconds
Resolution: 720-2160px
Max file size: 200MB
Max elements: 4 total (elements + reference images combined)

input_data = {
    # Required
    "prompt": "Change environment to be fully snow as @Image1. Replace animal with @Element1",
    "video_url": "https://example.com/video.mp4",    # .mp4/.mov, 3-10s, 720-2160px, max 200MB
# Optional
&quot;image_urls&quot;: [                                  # style/appearance references
    &quot;https://example.com/snow_ref.jpg&quot;           # use as @Image1, @Image2 in prompt
],
&quot;keep_audio&quot;: True,                              # keep original audio (default: true)
&quot;elements&quot;: [                                    # characters/objects to inject
    {
        &quot;reference_image_urls&quot;: [                # reference images for the element
            &quot;https://example.com/element_ref1.png&quot;
        ],
        &quot;frontal_image_url&quot;: &quot;https://example.com/element_front.png&quot;  # frontal view (better results)
    }
],                                               # use as @Element1, @Element2 in prompt
&quot;shot_type&quot;: &quot;customize&quot;                         # multi-shot type (default: customize)

}

Prompt references:

```
@Video1
```
— the input video
```
@Image1
```
,
```
@Image2
```
— reference images for style/appearance
```
@Element1
```
,
```
@Element2
```
— elements (characters/objects) to inject

Input Validation

The skill validates inputs before submission. For multi-input models, ensure all required fields are provided:

# Check what a model needs
python3 scripts/fal_client.py model-info "fal-ai/kling-video/o3/standard/video-to-video/edit"
List all models with their requirements

python3 scripts/fal_client.py models

Before submitting, verify:

✅ All
```
required
```
fields are present and non-empty
✅ File fields (
```
image_url
```
,
```
video_url
```
, etc.) are URLs or base64 data URIs
✅ Arrays (
```
image_urls
```
) have at least one item
✅ Video files are within limits (200MB, 720-2160p)

Example validation output:

⚠️  Note: Reference video in prompt as @Video1
⚠️  Note: Max 4 total elements (video + images combined)
❌ Validation failed:
   - Missing required field: video_url

Usage

CLI Commands

# Check API key
python3 scripts/fal_client.py check-key
Submit a request
python3 scripts/fal_client.py submit "fal-ai/nano-banana-pro" '{"prompt": "A sunset over mountains"}'
Check status
python3 scripts/fal_client.py status "fal-ai/nano-banana-pro" "<request_id>"
Get result
python3 scripts/fal_client.py result "fal-ai/nano-banana-pro" "<request_id>"
Poll all pending requests
python3 scripts/fal_client.py poll
List pending requests
python3 scripts/fal_client.py list
Convert local image to base64 data URI
python3 scripts/fal_client.py to-data-uri /path/to/image.jpg
Convert local video to base64 data URI (with validation)

python3 scripts/fal_client.py video-to-uri /path/to/video.mp4

Python Usage

import sys
sys.path.insert(0, 'scripts')
from fal_client import submit, check_status, get_result, image_to_data_uri, poll_pending
Text to image
result = submit('fal-ai/nano-banana-pro', {
'prompt': 'A futuristic city at night'
})
print(result['request_id'])
Image to image (with local file)
img_uri = image_to_data_uri('/path/to/photo.jpg')
result = submit('fal-ai/nano-banana-pro/edit', {
'prompt': 'Transform into watercolor painting',
'image_urls': [img_uri]
})
Poll until complete
completed = poll_pending()
for req in completed:
if 'result' in req:
print(req['result']['images'][0]['url'])

Queue System

fal.ai uses async queues. Requests go through stages:

```
IN_QUEUE
```
→ waiting
```
IN_PROGRESS
```
→ generating
```
COMPLETED
```
→ done, fetch result
```
FAILED
```
→ error occurred

Pending requests are saved to

~/. openclaw/workspace/fal-pending.json

and survive restarts.

Polling Strategy

Manual: Run

python3 scripts/fal_client.py poll

periodically.

Heartbeat: Add to

HEARTBEAT.md

- Poll fal.ai pending requests if any exist

Cron: Schedule polling every few minutes for background jobs.

Adding New Models

Find the model on fal.ai and check its
```
/api
```
page
Add entry to
```
references/models.json
```
with input/output schema
Test with a simple request

Note: Queue URLs use base model path (e.g.,

fal-ai/flux

not

fal-ai/flux/dev/image-to-image

). The script handles this automatically.

Files

skills/fal-ai/
├── SKILL.md                    ← This file
├── scripts/
│   └── fal_client.py           ← CLI + Python library
└── references/
    └── models.json             ← Model schemas

Troubleshooting

"No FAL_KEY found" → Add key to TOOLS.md or set FAL_KEY env var

405 Method Not Allowed → URL routing issue, ensure using base model path for status/result

Request stuck → Check

fal-pending.json

, may need manual cleanup

Fal Ai

AI Skill Market Insights

Be Part of the 0+ Developer Community

fal.ai Integration

Setup

Supported Models

fal-ai/nano-banana-pro (Text → Image)

fal-ai/nano-banana-pro/edit (Image → Image)

fal-ai/flux/dev/image-to-image (Image → Image)

fal-ai/kling-video/o3/pro/video-to-video/edit (Video → Video)

Input Validation

List all models with their requirements

Usage

CLI Commands

Submit a request

Check status

Get result

Poll all pending requests

List pending requests

Convert local image to base64 data URI

Convert local video to base64 data URI (with validation)

Python Usage

Text to image

Image to image (with local file)

Poll until complete

Queue System

Polling Strategy

Adding New Models

Files

Troubleshooting

Quick Start

Manual Installation

TEAR & SHARE

Tags

Channels

Learn

Compare

Company