Fal Ai

Generate images and media using fal.ai API (Flux, Gemini image, etc.). Use when asked to generate images, run AI image models, create visuals, or anything involving fal.ai. Handles queue-based requests with automatic polling.

Security Scan

The skill largely does what it says (submit and poll jobs to fal.ai), but metadata omits the required API key and the code reads local config files (TOOLS.md and ~/.openclaw/openclaw.json) for secrets — an inconsistency worth reviewing before installing.

Purpose & Capability

The code and SKILL.md match the stated purpose: submitting, polling, and retrieving image/video generation jobs from fal.ai queue endpoints (queue.fal.run and fal.ai storage). The included model schemas and CLI/python wrappers are consistent with an image/video generation client.

Instruction Scope

Runtime instructions and the script legitimately require reading local files for inputs (images/videos → base64 data URIs) and writing a pending requests file (~/.openclaw/workspace/fal-pending.json). However the script also reads ~/.openclaw/openclaw.json and ~/.openclaw/workspace/TOOLS.md to discover an API key; asking the agent to add secrets to TOOLS.md is a risky practice (it encourages storing credentials in a plaintext workspace file) and the regex-based key extraction could accidentally match other text. These behaviors expand the skill's access to local configuration beyond just reading the files you explicitly provide for image/video processing.

Install Mechanism

This is an instruction-only skill with an included Python script (no install spec). That is low-risk from an installer perspective. The script uses the 'requests' package but the skill metadata does not declare dependencies — users need Python and requests available in the environment.

Credentials

Registry metadata claims no required environment variables, but the script requires FAL_KEY (read from env var, ~/.openclaw/openclaw.json, or TOOLS.md). The skill does not request unrelated cloud credentials, but automatically reading openclaw.json and TOOLS.md can surface other stored config or accidentally match other keys. The credential access is limited to an API key for fal.ai, which is proportionate to the stated purpose, but the metadata/requirements mismatch is problematic and could mislead users about what will be accessed.

Persistence & Privilege

always:false (default) — the skill does not request forced/global presence. It persists a pending-requests JSON file under ~/.openclaw/workspace/fal-pending.json, which is reasonable for a queue client. It does not modify other skills or system-wide agent settings.

What to consider before installing

This skill appears to implement a fal.ai queue client that submits jobs, polls status, and fetches results — which matches its description. Before installing, consider the following: - You must provide an API key (FAL_KEY). The registry metadata says no env vars are required, but the code expects FAL_KEY (or a value in ~/.openclaw/openclaw.json under integrations.fal.apiKey, or in ~/.openclaw/workspace/TOOLS.md). That metadata mismatch is misleading. - The script reads ~/.openclaw/openclaw.json and TOOLS.md to find the key. Storing secrets in TOOLS.md (a workspace markdown file) is insecure; prefer setting FAL_KEY as an environment variable instead. - The client will read local files you point it at (images, videos) and will write a pending file to ~/.openclaw/workspace/fal-pending.json — review that file if you care about what persists on disk. - The code issues network requests to queue.fal.run and fal.ai storage endpoints. If you trust those endpoints and plan to use fal.ai, this is appropriate; otherwise review the URLs and code before use. - Ensure your environment has Python and the 'requests' library available; the skill does not declare dependencies. If you want to proceed safely: set FAL_KEY as an environment variable (do not place it in TOOLS.md), review scripts/fal_client.py locally to confirm behavior, and verify you trust the fal.ai endpoints. If you need absolute assurance, run the script in an isolated environment (container) so it cannot access unrelated config files.

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
    "image_urls": [                                  # style/appearance references
        "https://example.com/snow_ref.jpg"           # use as @Image1, @Image2 in prompt
    ],
    "keep_audio": True,                              # keep original audio (default: true)
    "elements": [                                    # characters/objects to inject
        {
            "reference_image_urls": [                # reference images for the element
                "https://example.com/element_ref1.png"
            ],
            "frontal_image_url": "https://example.com/element_front.png"  # frontal view (better results)
        }
    ],                                               # use as @Element1, @Element2 in prompt
    "shot_type": "customize"                         # 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

1. Find the model on fal.ai and check its /api page
2. Add entry to references/models.json with input/output schema
3. 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