名称： fal-ai
描述： 使用 fal.ai API（如 Flux、Gemini 图像等）生成图像和媒体。当被要求生成图像、运行 AI 图像模型、创建视觉效果或任何涉及 fal.ai 的操作时使用。处理基于队列的请求，并支持自动轮询。

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": "一只在月球上的宇航员猫",      # 必需
    "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 (严格) 到 6 (宽松)
}

fal-ai/nano-banana-pro/edit (图像 → 图像)

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

input_data = {
    "prompt": "转换为动漫风格",       # 必需
    "image_urls": [image_data_uri],               # 必需 - URL 或 base64 数据 URI 的数组
    "aspect_ratio": "auto",
    "resolution": "1K",
    "output_format": "png"
}

fal-ai/flux/dev/image-to-image (图像 → 图像)

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

input_data = {
    "prompt": "动漫风格肖像",             # 必需
    "image_url": image_data_uri,                  # 必需 - 单个 URL 或 base64 数据 URI
    "strength": 0.85,                             # 0-1，值越高变化越大
    "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 = {
    # 必需参数
    "prompt": "将环境完全变为 @Image1 中的雪景。用 @Element1 替换动物",
    "video_url": "https://example.com/video.mp4",    # .mp4/.mov 格式，3-10秒，720-2160像素，最大200MB

    # 可选参数
    "image_urls": [                                  # 风格/外观参考图像
        "https://example.com/snow_ref.jpg"           # 在提示词中引用为 @Image1, @Image2
    ],
    "keep_audio": True,                              # 保留原始音频 (默认: true)
    "elements": [                                    # 要注入的角色/对象
        {
            "reference_image_urls": [                # 元素的参考图像
                "https://example.com/element_ref1.png"
            ],
            "frontal_image_url": "https://example.com/element_front.png"  # 正面视图（效果更好）
        }
    ],                                               # 在提示词中引用为 @Element1, @Element2
    "shot_type": "customize"                         # 多镜头类型 (默认: customize)
}

提示词引用：
- @Video1 — 输入视频
- @Image1, @Image2 — 风格/外观的参考图像
- @Element1, @Element2 — 要注入的元素（角色/对象）

输入验证

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

# 检查模型所需参数
python3 scripts/fal_client.py model-info "fal-ai/kling-video/o3/standard/video-to-video/edit"

# 列出所有模型及其要求
python3 scripts/fal_client.py models

提交前，请验证：
- ✅ 所有 required 字段都存在且非空
- ✅ 文件字段（image_url、video_url 等）是 URL 或 base64 数据 URI
- ✅ 数组（image_urls）至少包含一项
- ✅ 视频文件符合限制（200MB，720-2160p）

验证输出示例：

⚠️  注意：在提示词中将参考视频引用为 @Video1
⚠️  注意：最多 4 个总元素（视频 + 图像合计）
❌ 验证失败：
   - 缺少必填字段：video_url

使用方法

命令行命令

# 检查 API 密钥
python3 scripts/fal_client.py check-key

# 提交请求
python3 scripts/fal_client.py submit "fal-ai/nano-banana-pro" '{"prompt": "山上的日落"}'

# 检查状态
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

# 将本地图像转换为 base64 数据 URI
python3 scripts/fal_client.py to-data-uri /path/to/image.jpg

# 将本地视频转换为 base64 数据 URI（带验证）
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

# 文生图
result = submit('fal-ai/nano-banana-pro', {
    'prompt': '夜晚的未来城市'
})
print(result['request_id'])

# 图生图（使用本地文件）
img_uri = image_to_data_uri('/path/to/photo.jpg')
result = submit('fal-ai/nano-banana-pro/edit', {
    'prompt': '转换为水彩画风格',
    'image_urls': [img_uri]
})

# 轮询直到完成
completed = poll_pending()
for req in completed:
    if 'result' in req:
        print(req['result']['images'][0]['url'])

队列系统

fal.ai 使用异步队列。请求会经历以下阶段：
- IN_QUEUE → 等待中
- IN_PROGRESS → 生成中
- COMPLETED → 完成，可获取结果
- FAILED → 发生错误

待处理的请求会保存到 ~/.openclaw/workspace/fal-pending.json 文件中，并在重启后保留。

轮询策略

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

心跳轮询： 添加到 HEARTBEAT.md：

- 如果存在任何待处理请求，则轮询 fal.ai

定时任务： 为后台作业安排每隔几分钟轮询一次。

添加新模型

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                    ← 本文档
├── scripts/
│   └── fal_client.py           ← CLI + Python 库
└── references/
    └── models.json             ← 模型模式定义

故障排除

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

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

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