跳到主要内容

图像生成

KOPI AI AGENT 通过 FAL.ai 根据文本提示词生成图像。开箱即用支持十一个模型,每个模型在速度、质量和成本上各有取舍。当前使用的模型可通过 kopi tools 由用户配置,并持久化保存在 config.yaml 中。

支持的模型​

模型速度优势价格
fal-ai/flux-2/klein/9b (默认)<1s速度快,文字清晰$0.006/MP
fal-ai/flux-2-pro约 6 秒影棚级照片写实$0.03/MP
fal-ai/z-image/turbo约 2 秒中英双语,60 亿参数$0.005/MP
fal-ai/nano-banana-pro约 8 秒Gemini 3 Pro,推理深度强,文字渲染$0.15/图像(1K)
fal-ai/gpt-image-1.5约 15 秒提示词遵循度高$0.034/图像
fal-ai/gpt-image-2约 20 秒SOTA 级文字渲染 + CJK 支持,具备世界知识的照片写实$0.04–0.06/图像
fal-ai/ideogram/v3约 5 秒最佳排版效果$0.03–0.09/图像
fal-ai/recraft/v4/pro/text-to-image约 8 秒设计、品牌系统,可直接投产$0.25/图像
fal-ai/qwen-image约 12 秒基于 LLM,擅长复杂文本$0.02/MP
fal-ai/krea/v2/medium/text-to-image约 15-25 秒插画、动漫、绘画,富有表现力/艺术风格$0.030–0.035/图像
fal-ai/krea/v2/large/text-to-image约 25-60 秒照片写实,原始质感效果(运动模糊、颗粒、胶片)$0.060–0.065/图像

以上价格为撰写本文时 FAL 的定价;请访问 fal.ai 查看最新价格。

配置​

Nous 订阅用户

如果你拥有付费的 KOPI Proxy 订阅,可以无需 FAL API key,直接通过 Tool Gateway 使用图像生成。你在两种路径下的模型选择会保持同步。新安装可运行 kopi setup --portal 一次性登录并启用所有网关工具;已有安装可通过 kopi tools 将 Nous Subscription 选为图像生成后端。

如果托管网关针对某个特定模型返回 HTTP 4xx,说明该模型尚未在门户侧完成代理——agent 会告知你这一点,并给出补救步骤(设置 FAL_KEY 进行直连,或改选其他模型)。

获取 FAL API Key​

  1. 在 fal.ai 注册账号
  2. 在控制面板中生成 API key

配置并选择模型​

运行工具命令:

kopi tools

进入 🎨 Image Generation,选择后端(Nous Subscription 或 FAL.ai),然后选择器会以列对齐的表格展示所有支持的模型——使用方向键移动,回车键确认选择:

  Model                          Speed    Strengths                    Price
fal-ai/flux-2/klein/9b <1s Fast, crisp text $0.006/MP ← currently in use
fal-ai/flux-2-pro ~6s Studio photorealism $0.03/MP
fal-ai/z-image/turbo ~2s Bilingual EN/CN, 6B $0.005/MP
...

你的选择会保存到 config.yaml:

image_gen:
model: fal-ai/flux-2/klein/9b
use_gateway: false # true if using Nous Subscription

GPT-Image 质量​

fal-ai/gpt-image-1.5 和 fal-ai/gpt-image-2 请求的质量固定为 medium(1024×1024 下约 $0.034–$0.06/图像)。我们不将 low / high 档位作为面向用户的选项暴露出来,以确保所有用户的 KOPI Proxy 计费保持可预测——各档位之间的成本差距为 3–22 倍。如果你想要更便宜的选项,可选择 Klein 9B 或 Z-Image Turbo;如果想要更高的质量,可使用 Nano Banana Pro 或 Recraft V4 Pro。

使用方法​

面向 agent 的 schema 刻意保持极简——模型会直接采用你已配置的设置:

Generate an image of a serene mountain landscape with cherry blossoms
Create a square portrait of a wise old owl — use the typography model
Make me a futuristic cityscape, landscape orientation

图生图 / 图像编辑​

同一个 image_generate 工具在当前模型支持时还能编辑现有图像——传入源图像后,后端会自动路由到其编辑端点(与 video_generate 处理图生视频的方式一致)。 省略源图像时即为纯文生图。

Take this photo and make it a rainy Tokyo street at night → <image>
Blend these two product shots into one hero image → <image1> <image2>

编辑由两个输入驱动:

  • image_url —— 要编辑/变换的主要源图像(公开 URL 或本地路径)。
  • reference_image_urls —— 额外的风格/构图参考(每个模型有数量上限)。

哪些后端支持编辑​

后端图生图参考图上限实现方式
FAL.ai(下方支持编辑的模型)✓最多 9 张路由到模型的 /edit 端点
OpenAI (gpt-image-2)✓最多 16 张images.edit()
xAI (Grok Imagine)✓1 张/v1/images/edits (grok-imagine-image-quality)
Krea (Krea 2)✓最多 10 张参考图引导生成 (image_style_references)
OpenAI (Codex auth)✓最多 16 张Codex Responses image_generation 工具搭配 input_image 内容分片

带编辑端点的 FAL 模型:flux-2/klein/9b、flux-2-pro、 nano-banana-pro、gpt-image-1.5、gpt-image-2、ideogram/v3 以及 qwen-image。纯文生图的 FAL 模型(z-image/turbo、recraft、 krea/*)会拒绝图像输入,并给出清晰的错误信息,引导你改用支持编辑的模型。

当前模型的编辑能力会在运行时出现在工具描述中,因此 agent 在调用工具之前就知道 image_url 是否会被采纳。

宽高比​

从 agent 的视角来看,每个模型都接受同样的三种宽高比。在内部,每个模型的原生尺寸规格会被自动填充:

Agent 输入image_size (flux/z-image/qwen/recraft/ideogram)aspect_ratio (nano-banana-pro)image_size (gpt-image-1.5)image_size (gpt-image-2)
landscapelandscape_16_916:91536x1024landscape_4_3 (1024×768)
squaresquare_hd1:11024x1024square_hd (1024×1024)
portraitportrait_16_99:161024x1536portrait_4_3 (768×1024)

GPT Image 2 映射到 4:3 预设而非 16:9,因为其最低像素数为 655,360——landscape_16_9 预设(1024×576 = 589,824)会被拒绝。

该转换在 _build_fal_payload() 中完成——agent 代码无需了解各模型的 schema 差异。

自动放大​

通过 FAL 的 Clarity Upscaler 进行放大按模型划分:

模型是否放大原因
fal-ai/flux-2-pro✓向后兼容(曾是选择器之前的默认设置)
其他所有模型✗快速模型会失去其亚秒级的价值优势;高分辨率模型则无需放大

当放大执行时,使用以下设置:

设置值
放大倍数2×
Creativity0.35
Resemblance0.6
Guidance scale4
Inference steps18

如果放大失败(网络问题、速率限制),将自动返回原始图像。

内部工作原理​

  1. Model resolution — _resolve_fal_model() 读取 image_gen.model(来自 config.yaml),若未设置则回退到 FAL_IMAGE_MODEL 环境变量,最后回退到 fal-ai/flux-2/klein/9b。
  2. Payload building — _build_fal_payload() 将你的 aspect_ratio 翻译为模型的原生格式(preset 枚举、aspect-ratio 枚举或 GPT 字面量),合并模型的默认参数,应用调用方的任意覆盖值,然后过滤到模型的 supports 白名单,确保不支持的键永远不会被发送。
  3. Submission — _submit_fal_request() 通过直接的 FAL 凭据或托管的 Nous gateway 路由。
  4. Upscaling — 仅在模型的 metadata 含有 upscale: True 时运行。
  5. Delivery — 最终图片 URL 返回给 agent,由其发出一个 MEDIA:<url> 标签,平台适配器会将其转换为原生媒体。

调试​

启用 debug logging:

export IMAGE_TOOLS_DEBUG=true

Debug 日志会输出到 ./logs/image_tools_debug_<session_id>.json,包含每次调用的详细信息(model、参数、耗时、错误)。

平台投递​

平台投递方式
CLI图片 URL 以 markdown ![](url) 形式打印 — 点击即可打开
Telegram照片消息,prompt 作为说明文字
Discord嵌入在消息中
SlackURL 由 Slack 展开预览
WhatsApp媒体消息
其他纯文本中的 URL

限制​

  • Requires credentials — 需要为当前活跃的 backend(FAL FAL_KEY / Nous Subscription、OPENAI_API_KEY、xAI OAuth、KREA_API_KEY)提供凭据
  • Editing is model-dependent — image-to-image 仅在支持编辑的模型上可用(见上表);仅支持 text-to-image 的模型会以明确的错误拒绝图片输入
  • Temporary URLs — backend 返回的托管 URL 会在数小时/数天后过期;Kopi Agent 会将其固化到本地缓存,因此过期后投递仍然有效
  • Per-model constraints — 部分模型不支持 seed、num_inference_steps 等。supports / edit_supports 过滤器会静默丢弃不支持的参数;这是预期行为