fal.ai 集成

通过 fal.ai 基于队列的 API 生成和编辑图像。

设置

将您的 API 密钥添加到TOOLS.md中：

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

在此处获取密钥：https://fal.ai/dashboard/keys

脚本按以下顺序检查：FAL_KEY环境变量 →TOOLS.md

支持的模型

fal-ai/nano-banana-pro（文本 → 图像）

Google 的 Gemini 3 Pro 模型，用于文生图。

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（图像 → 图像）

Gemini 3 Pro 模型，用于图像编辑。速度较慢（约20秒），但能很好地处理复杂编辑。

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（图像 → 图像）

FLUX.1 dev 模型。用于风格转换，速度更快（约2-3秒）。

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（视频 → 视频）

Kling O3 Pro 模型，用于通过 AI 特效进行视频变换。

限制：

• 格式：仅限 .mp4、.mov
• 时长：3-10 秒
• 分辨率：720-2160 像素
• 最大文件大小：200MB
• 最大元素数量：总计 4 个（元素与参考图片合计）

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)
}

提示词参考：

• @Video1— 输入视频
• @Image1、@Image2— 风格/外观的参考图片
• @Element1、@Element2— 要注入的元素（角色/物体）

输入验证

该技能会在提交前验证输入。对于多输入模型，需确保提供所有必填字段：

# 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

提交前请验证：

• ✅ 所有必填字段均已填写且非空
• ✅ 文件字段（image_url、video_url等）为URL或base64数据URI格式
• ✅ 数组字段（image_urls）至少包含一项
• ✅ 视频文件符合限制要求（200MB，720-2160p分辨率）

验证输出示例：

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

使用方式

命令行指令

# 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使用方式

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'])

队列系统

fal.ai采用异步队列系统。请求将经历以下阶段：

• 队列中→ 等待处理
• 处理中→ 生成中
• 已完成→ 完成，获取结果
• 失败→ 发生错误

待处理请求已保存至~/.openclaw/workspace/fal-pending.json并在重启后保留。

轮询策略

手动：运行python3 scripts/fal_client.py poll定期执行。

心跳：添加到HEARTBEAT.md：

- Poll fal.ai pending requests if any exist

Cron：为后台作业安排每隔几分钟轮询一次。

添加新模型

1. 在 fal.ai 上找到模型并查看其/api页面
2. 将条目添加到references/models.json包含输入/输出模式
3. 使用一个简单的请求进行测试

注意：队列URL使用基础模型路径（例如，fal-ai/flux而不是fal-ai/flux/dev/image-to-image）。脚本会自动处理这一点。

文件

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

故障排除

"未找到 FAL_KEY"→ 将密钥添加到 TOOLS.md 或设置 FAL_KEY 环境变量

405 方法不允许→ URL路由问题，请确保对状态/结果使用基础模型路径

请求卡住→ 检查fal-pending.json文件，可能需要手动清理