fal-ai-image

fal-ai-image

通过 fal.ai 生成图像。此技能现支持两种由 fal 托管的模型：

• Google Nano Banana Pro（fal-ai/nano-banana-pro）——默认模型，向后兼容
• OpenAI GPT Image 2（openai/gpt-image-2）——通过 config/.env 启用

Agent 应将以下称谓视为等同：

• gpt = openai = GPT Image 2
• nano banana = google = gemini = Nano Banana Pro

适用于：信息图、文本渲染、横幅、照片编辑、基于参考图的构图。

停止——操作前请阅读

• 不要使用 Pillow、ImageMagick 或后期处理来叠加文本／徽标，除非用户明确要求采用该工作流
• 不要在用户提供参考图时使用生成模式——请使用编辑模式
• 不要假定 GPT 已启用——检查 config/README.md 中的逻辑；如果未配置选择器，此技能将继续使用 Nano Banana
• 不要猜测特定提供方的参数——Nano Banana 和 GPT Image 2 使用不同的架构
• 用户明确指定某个模型／提供方或要求比较提供方时，请传入 --model ...
• 不要跳过本地文件上传——先运行 upload.sh，获取供 edit.sh 使用的 URL

快速入门决策

Reference images provided?  -> Edit mode   (upload.sh -> edit.sh)
Text-only generation?       -> Generate mode (generate.sh)

Model comes from config/.env:
  no selector set           -> Nano Banana Pro
  FAL_IMAGE_PROVIDER=openai -> GPT Image 2
  FAL_IMAGE_MODEL=...       -> exact override

配置

需要在 config/.env 或环境中设置 FAL_KEY。

模型选择：

1. --model——仅覆盖当前命令
2. FAL_IMAGE_MODEL——配置中的精确覆盖项
3. FAL_IMAGE_PROVIDER——google 或 openai
4. 未设置任何选项——默认使用 Nano Banana Pro

用户明确提出以下要求时，请使用 --model：

• “сделай через GPT”
• “используй OpenAI”
• “сделай через Google / Gemini / Nano Banana”
• “какие тут есть провайдеры?”

回答时说明此技能支持两种选择，并按以下方式映射命令：

• OpenAI GPT Image 2 使用 --model gpt
• Nano Banana 使用 --model gemini 或 --model nano-banana

OpenAI 默认质量设置：

• 除非通过 --quality 覆盖，否则 FAL_IMAGE_OPENAI_QUALITY=medium
• 此技能特意将 GPT 的默认质量设为 medium，以避免探索性运行产生高额费用

完整的设置与故障排除说明：config/README.md。

仅在需要时阅读参考文档：

• references/MODELS.md——选择器优先级、别名、成本估算
• references/EDITING.md——生成与编辑、mask_url、图像修补行为

模型说明

Nano Banana Pro

优势：

• 现有安装的默认选项，使用门槛更低
• 文本渲染能力强，包括西里尔字母
• 擅长信息图、横幅以及文本与图像混合布局
• 在生成模式下支持 --web-search

主要参数：

• --aspect-ratio
• --resolution
• --web-search（仅用于生成）

OpenAI GPT Image 2

优势：

• 更能遵循提示词，支持更精细的编辑
• 写实效果和产品风格渲染更出色
• 原生支持 quality 控制
• 通过 fal 使用相同的 FAL_KEY，无需单独的 OpenAI 密钥
• 当前 fal 定价取决于尺寸／质量；粗略估算高质量图像的价格约为每张 $0.18，但在报出确切价格前请查看模型实时页面

主要参数：

• --image-size
• --quality

兼容层：

• 如果省略 --image-size，脚本会根据 --aspect-ratio + --resolution 推导有效的 OpenAI image_size
• 这样在配置中切换提供方后，旧提示词仍可继续使用

工作流

生成模式

1. 根据配置决定模型
2. 仅在需要时补充缺失参数：
   • Nano Banana：宽高比、分辨率
   • GPT Image 2：图像尺寸和质量
3. 根据项目结构建议保存路径
4. 运行 generate.sh
5. 解析结果 JSON；如果已下载，则报告 URL 和本地文件

编辑模式

1. 获取参考图：
   • 已有 URL → 直接使用
   • 本地文件 → 使用 upload.sh
2. 根据配置决定模型
3. 确认编辑意图
4. 运行 edit.sh
5. 解析结果 JSON；如果已下载，则报告 URL 和本地文件

脚本

generate.sh

Nano Banana 示例：

sh scripts/generate.sh \
  --model "gemini" \
  --prompt "infographic about coffee brewing" \
  --aspect-ratio "9:16" \
  --resolution "1K" \
  --output-dir "./images" \
  --filename "coffee_infographic"

GPT Image 2 示例：

sh scripts/generate.sh \
  --model "gpt" \
  --prompt "realistic product hero shot with sharp packaging text" \
  --image-size "landscape_4_3" \
  --quality "medium" \
  --output-dir "./images" \
  --filename "product_hero"

GPT 兼容性示例：

sh scripts/generate.sh \
  --model "openai" \
  --prompt "editorial portrait, window light, magazine cover layout" \
  --aspect-ratio "4:3" \
  --resolution "2K"

参数	必填	默认值	说明
--prompt	是	-	文本提示词
--model	否	配置 / Nano Banana 回退选项	nano-banana、google、gemini、gpt、openai 或确切端点
--aspect-ratio	否	1:1	Nano 原生参数；对于 GPT，仅在省略 --image-size 时使用
--resolution	否	1K	Nano 原生参数；对于 GPT，仅在省略 --image-size 时使用
--image-size	否	根据比例/分辨率推导	仅适用于 GPT；预设值（landscape_4_3）或 WIDTHxHEIGHT
--quality	否	通过配置设为 medium	仅适用于 GPT；low、medium、high
--num-images	否	1	1-4
--output-format	否	png	jpeg、png、webp
--output-dir	否	-	本地路径
--filename	否	generated	基础文件名
--web-search	否	false	仅适用于 Nano；GPT 会忽略此参数

edit.sh

Nano Banana 示例：

sh scripts/edit.sh \
  --model "gemini" \
  --prompt "combine these into a collage" \
  --image-urls "https://example.com/img1.png,https://example.com/img2.png" \
  --aspect-ratio "16:9" \
  --output-dir "./images" \
  --filename "collage"

GPT Image 2 示例：

sh scripts/edit.sh \
  --model "gpt" \
  --prompt "make this product shot look like a premium studio campaign" \
  --image-urls "https://example.com/source.png" \
  --mask-url "https://example.com/mask.png" \
  --image-size "auto" \
  --quality "medium" \
  --output-dir "./images" \
  --filename "studio_edit"

参数	必填	默认值	说明
--prompt	是	-	编辑指令
--image-urls	是	-	以逗号分隔的 URL
--model	否	配置 / Nano Banana 回退选项	nano-banana、google、gemini、gpt、openai 或确切端点
--mask-url	否	-	仅适用于 GPT 编辑；用于定向编辑的可选蒙版
--aspect-ratio	否	auto	Nano 原生参数；对于 GPT，仅在省略 --image-size 时使用
--resolution	否	1K	Nano 原生参数；对于 GPT，仅在省略 --image-size 时使用
--image-size	否	根据比例/分辨率推导 / auto	仅适用于 GPT
--quality	否	通过配置设为 medium	仅适用于 GPT
--num-images	否	1	1-4
--output-format	否	png	jpeg、png、webp
--output-dir	否	-	本地路径
--filename	否	edited	基础文件名

upload.sh

# Get hosted URL for local file
URL=$(sh scripts/upload.sh --file /path/to/image.png)

# Get base64 data URI for manual API work
URI=$(sh scripts/upload.sh --file /path/to/image.png --base64)

费用指南

• Nano Banana Pro 是更经济、更稳妥的快速迭代默认选项
• GPT Image 2 的费用很大程度上取决于 quality 和 image_size
• 此技能默认将 GPT 质量设为 medium，以减少意外支出

如需了解当前定价，请查看 fal 的模型页面，参见 config/README.md。

备注

• 结果 URL 大约一小时后过期——如需长期保存，请下载到本地
• fal 存储中的上传文件是临时的
• edit.sh 现在会轮询 fal 文档中说明的同一组 /edit 队列端点