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.
Generate and edit images via fal.ai's queue-based API.
Add your API key to `TOOLS.md`:
```markdown
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`
Google's Gemini 3 Pro for text-to-image generation.
```python
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)
}
```
Gemini 3 Pro for image editing. Slower (~20s) but handles complex edits well.
```python
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"
}
```
FLUX.1 dev model. Faster (~2-3s) for style transfers.
```python
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"
}
```
```bash
python3 scripts/fal_client.py check-key
python3 scripts/fal_client.py submit "fal-ai/nano-banana-pro" '{"prompt": "A sunset over mountains"}'
python3 scripts/fal_client.py status "fal-ai/nano-banana-pro" "<request_id>"
python3 scripts/fal_client.py result "fal-ai/nano-banana-pro" "<request_id>"
python3 scripts/fal_client.py poll
python3 scripts/fal_client.py list
python3 scripts/fal_client.py to-data-uri /path/to/image.jpg
```
```python
import sys
sys.path.insert(0, 'scripts')
from fal_client import submit, check_status, get_result, image_to_data_uri, poll_pending
result = submit('fal-ai/nano-banana-pro', {
'prompt': 'A futuristic city at night'
})
print(result['request_id'])
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]
})
completed = poll_pending()
for req in completed:
if 'result' in req:
print(req['result']['images'][0]['url'])
```
fal.ai uses async queues. Requests go through stages:
Pending requests are saved to `~/. openclaw/workspace/fal-pending.json` and survive restarts.
**Manual:** Run `python3 scripts/fal_client.py poll` periodically.
**Heartbeat:** Add to `HEARTBEAT.md`:
```markdown
```
**Cron:** Schedule polling every few minutes for background jobs.
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.
```
skills/fal-ai/
├── SKILL.md ← This file
├── scripts/
│ └── fal_client.py ← CLI + Python library
└── references/
└── models.json ← Model schemas
```
**"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
Leave a review
No reviews yet. Be the first to review this skill!