# Send Fal Ai to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "falai", "name": "Fal Ai", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/Sxela/falai", "canonicalUrl": "https://clawhub.ai/Sxela/falai", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/falai", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=falai", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md", "references/models.json", "scripts/fal_client.py" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "falai", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-03T03:10:47.745Z", "expiresAt": "2026-05-10T03:10:47.745Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=falai", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=falai", "contentDisposition": "attachment; filename=\"falai-1.0.2.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "falai" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/falai" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/falai", "downloadUrl": "https://openagent3.xyz/downloads/falai", "agentUrl": "https://openagent3.xyz/skills/falai/agent", "manifestUrl": "https://openagent3.xyz/skills/falai/agent.json", "briefUrl": "https://openagent3.xyz/skills/falai/agent.md" } } ``` ## Documentation ### 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 ### 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 ### 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" "" # Get result python3 scripts/fal_client.py result "fal-ai/nano-banana-pro" "" # 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 ## Trust - Source: tencent - Verification: Indexed source record - Publisher: Sxela - Version: 1.0.2 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-05-03T03:10:47.745Z - Expires at: 2026-05-10T03:10:47.745Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/falai) - [Send to Agent page](https://openagent3.xyz/skills/falai/agent) - [JSON manifest](https://openagent3.xyz/skills/falai/agent.json) - [Markdown brief](https://openagent3.xyz/skills/falai/agent.md) - [Download page](https://openagent3.xyz/downloads/falai)