图像生成
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 查看最新价格。
配置
如果你拥有付费的 KOPI Proxy 订阅,可以无需 FAL API key,直接通过 Tool Gateway 使用图像生成。你在两种路径下的模型选择会保持同步。新安装可运行 kopi setup --portal 一次性登录并启用所有网关工具;已有安装可通过 kopi tools 将 Nous Subscription 选为图像生成后端。
如果托管网关针对某个特定模型返回 HTTP 4xx,说明该模型尚未在门户侧完成代理——agent 会告知你这一点,并给出补救步骤(设置 FAL_KEY 进行直连,或改选其他模型)。
获取 FAL API Key
- 在 fal.ai 注册账号
- 在控制面板中生成 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) |
|---|---|---|---|---|
landscape | landscape_16_9 | 16:9 | 1536x1024 | landscape_4_3 (1024×768) |
square | square_hd | 1:1 | 1024x1024 | square_hd (1024×1024) |
portrait | portrait_16_9 | 9:16 | 1024x1536 | portrait_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× |
| Creativity | 0.35 |
| Resemblance | 0.6 |
| Guidance scale | 4 |
| Inference steps | 18 |
如果放大失败(网络问题、速率限制),将自动返回原始图像。
内部工作原理
- Model resolution —
_resolve_fal_model()读取image_gen.model(来自config.yaml),若未设置则回退到FAL_IMAGE_MODEL环境变量,最后回退到fal-ai/flux-2/klein/9b。 - Payload building —
_build_fal_payload()将你的aspect_ratio翻译为模型的原生格式(preset 枚举、aspect-ratio 枚举或 GPT 字面量),合并模型的默认参数,应用调用方的任意覆盖值,然后过滤到模型的supports白名单,确保不支持的键永远不会被发送。 - Submission —
_submit_fal_request()通过直接的 FAL 凭据或托管的 Nous gateway 路由。 - Upscaling — 仅在模型的 metadata 含有
upscale: True时运行。 - Delivery — 最终图片 URL 返回给 agent,由其发出一个
MEDIA:<url>标签,平台适配器会将其转换为原生媒体。
调试
启用 debug logging:
export IMAGE_TOOLS_DEBUG=true
Debug 日志会输出到 ./logs/image_tools_debug_<session_id>.json,包含每次调用的详细信息(model、参数、耗时、错误)。
平台投递
| 平台 | 投递方式 |
|---|---|
| CLI | 图片 URL 以 markdown  形式打印 — 点击即可打开 |
| Telegram | 照片消息,prompt 作为说明文字 |
| Discord | 嵌入在消息中 |
| Slack | URL 由 Slack 展开预览 |
| 媒体消息 | |
| 其他 | 纯文本中的 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过滤器会静默丢弃不支持的参数;这是预期行为