FLUX 生图/编辑

概述

FLUX 是德国 Black Forest Labs（BFL）推出的旗舰图像生成模型族。最新一代 FLUX.2 横跨 sub-second 到 4MP 旗舰画质共 5 档，叠加上一代图像编辑专用的 FLUX.1 Kontext 共 7 个模型在售；老版本 FLUX.1 [pro] 系列也保留可调用。API易网关把 BFL 的异步 API 封装成标准 OpenAI Images API（/v1/images/generations 与 /v1/images/edits），OpenAI 官方 SDK 把 base_url 指过来即可零代码改动直连。

🎨 核心亮点：FLUX.2 [max] 独家支持 grounding search 联网搜索，原生 4MP 输出（2048×2048）+ 多参考图最多 8 张 + 32K tokens 长 prompt + hex 色精确控制 + 文字渲染领先。适合需要旗舰画质、多图一致性、品牌色精确还原、专业排版 的生产场景。

文生图 API

/v1/images/generations，输入文本提示词生成图片，覆盖 FLUX.2 全部 5 个模型。

图片编辑 API

/v1/images/edits，multipart 上传参考图（最多 8 张）+ 编辑/融合指令，FLUX.2 + FLUX.1 Kontext 通用。

历史版本

FLUX.1 [pro] / [pro] 1.1 / [pro] 1.1 Ultra / [dev] 老版本规格、迁移建议、计费差异。

为什么选 API易的 FLUX？

对标 BFL 官方通道，针对企业生产场景在 稳定性、成本、接入体验 三方面做了深度优化：

OpenAI 兼容封装 · 零代码迁移

BFL 官方走异步 polling，APIYI 把它封装成同步的 OpenAI Images API。OpenAI 官方 SDK 把 base_url 指过来直接用，不用自己写 polling_url 轮询循环。

不限并发 · 突破 24 active 限制

BFL 官方对单账号限 24 个 active tasks（kontext-max 仅 6），APIYI 在网关层做了池化，企业用户线性放量不受单账号限制。

同价或最高节省 17%

FLUX.2 [pro/max/flex] 与官方 1MP 同价，klein 4B/9B 比官方更便宜（节省约 28%），FLUX.1 [pro] 1.1 Ultra 节省 17%，叠加充值加赠活动 最低可享 85 折。

全球零门槛接入

无需海外服务器或代理，国内机房、家宽网络、海外节点均可直连 api.apiyi.com，延迟稳定、免去出海改造。

模型生态齐全

搭配 gpt-image-2、Seedream、Nano Banana 等同站系列，可按场景自由组合。

专业服务 · 企业陪跑

团队深耕图像生成场景，具备丰富的选型、调优与集成经验，可为企业客户提供从 PoC 到生产上线的完整技术支持。

核心特性

速度全档位覆盖

klein 4B/9B sub-second 出图（消费级 GPU 即可）、pro < 10 秒、max < 15 秒、flex 较慢但精度更高。一个系列横跨实时到旗舰。

原生 4MP 输出

最大 2048×2048（约 4MP），是 FLUX.1 时代 1.6MP 的 2.5 倍。任意宽高（边长须 16 倍数），最小 64×64。

多参考图融合

image[] 数组上传多张参考图：FLUX.2 [pro/max/flex] 最多 8 张，[klein] 最多 4 张，prompt 中可用「图1/图2」精确指代。

联网搜索（grounding search）

FLUX.2 [max] 独家：prompt 触发实时网络检索，可生成”昨日比赛比分”、“实时天气”、“历史事件复刻”等需要外部知识的画面。

精确 hex 色控制

在 prompt 里直接写 #02eb3c / #ff0088 等 hex 码，模型按精确色值出图，专业品牌设计无需后期调色。

32K tokens 长 prompt

支持最长 32K tokens 的 prompt，可用结构化 JSON 描述（subject / background / lighting / style 等），适合产线自动化。

文字渲染特化

FLUX.2 [flex] 专为文字场景调优，海报标题、UI 截图、信息图等小字保留度业内领先；max / pro 同样可用。

OpenAI SDK 直连

把 base_url 指向 https://api.apiyi.com/v1 即可用 OpenAI 官方 SDK 直接调 client.images.generate(model="flux-2-pro", ...)，零代码改动。

模型定价

按次计费，单价见下表（APIYI 单价列）。BFL 官方按 MP（megapixel） 计费，1MP 内同价、超过逐 MP 加成；APIYI 按张定价更可预测。

FLUX.2 系列（最新一代）

模型 ID	APIYI 单价	官方价	速度	适用场景
`flux-2-max`	$0.0700/次	from $0.07/MP	< 15 秒	旗舰画质 + 联网搜索（grounding）
`flux-2-pro`	$0.0300/次	from $0.03/MP	< 10 秒	生产规模、最佳性价比
`flux-2-flex`	$0.0600/次	$0.06/MP	较慢	文字渲染特化，可调 steps/guidance
`flux-2-klein-9b`	$0.0100/次	from $0.015	sub-second	平衡画质和速度
`flux-2-klein-4b`	$0.0100/次	from $0.014	sub-second	最快、消费级 GPU 友好

FLUX.1 Kontext 系列（图像编辑专用）

模型 ID	APIYI 单价	官方价	节省	适用场景
`flux-kontext-max`	$0.0700/次	$0.08	12.5%	编辑最高质量、文字精修
`flux-kontext-pro`	$0.0350/次	$0.04	12.5%	编辑性价比首选、5-6 秒生成

FLUX.1 [pro] 经典版本（历史版本，仍可调用）

模型 ID	APIYI 单价	官方价	节省
`flux-pro-1.1-ultra`	$0.0500/次	$0.06	17%
`flux-pro-1.1`	$0.0350/次	$0.04	12.5%
`flux-pro`	$0.0400/次	$0.04	同价
`flux-dev`	$0.0200/次	—	—

详细规格与迁移建议见历史版本页。

计费说明：

APIYI 走按次定价，1 张图固定单价，与输出 MP 无关
官方按 MP 计费，1MP 起步价 + 超过部分逐 MP 加成
编辑请求与文生图同价（不像 OpenAI gpt-image-2 编辑要按 Vision 加价）
klein 4B / klein 9B 的开源权重可在 Hugging Face 自行部署（Apache 2.0 / FLUX NCL 协议）
失败请求（4xx / 内容审核拦截）不计费

技术规格

维度	参数
当前主力推荐	`flux-2-pro` / `flux-2-pro-preview`（综合）+ `flux-kontext-max`（编辑文字）
速度	sub-second（klein）/ < 10 秒（pro）/ < 15 秒（max）/ 较慢（flex）
输出分辨率	最大 4MP（2048×2048），任意宽高，边长须 16 倍数
输入分辨率	最小 64×64，最大 4MP（仅编辑端点）
参考图上限	8 张（FLUX.2 [pro/max/flex]）/ 4 张（FLUX.2 [klein]）/ 1 张（FLUX.1 Kontext）
Prompt 长度	最长 32K tokens
输出格式	`jpeg`（默认）/ `png`
审核档位	`safety_tolerance` 0–6（0 最严、6 最宽松，默认 2）
联网搜索	仅 `flux-2-max` 支持 grounding search
响应字段	`data[0].url`（10 分钟内有效，需立即下载）
单次出图数量	1 张（`n=1`）
prompt_upsampling	FLUX.2 [pro/max/flex] 支持，[klein] 不支持

端点一览

端点	用途	Content-Type
`POST /v1/images/generations`	文生图（所有 FLUX 模型）	`application/json`
`POST /v1/images/edits`	图像编辑 / 多图融合（FLUX.2 + Kontext）	`multipart/form-data`

域名选择：api.apiyi.com 为主域名，也可使用 b.apiyi.com / vip.apiyi.com 等平台提供的其他网关域名，响应行为一致。

尺寸（width / height）详解

常用尺寸

尺寸	含义	像素	适用
`1024x1024`	方形 1:1	~1MP	通用、社媒头像
`1024x1536`	竖版 2:3	~1.6MP	海报、肖像
`1536x1024`	横版 3:2	~1.6MP	风景、桌面
`1440x2048`	竖版 ~3:4	~2.9MP	电影竖幅
`1920x1080`	横版 16:9	~2MP	视频缩略图
`2048x2048`	方形 1:1	4MP	旗舰打印（FLUX.2 上限）

自定义尺寸约束

FLUX.2 接受任意尺寸，只需同时满足：

width / height 都是 16 的倍数
最小 64×64
最大约 4MP（如 2048×2048 / 1920×2048 / 2048×1920 等）
推荐总像素 ≤ 2MP 以兼顾速度与价格

合法示例：1280x720、1920x1080、2048x1024、1456x1920 非法示例：1000x1000（非 16 倍数）、3840x2160（超 4MP 上限）、32x32（小于 64×64）

API 端 width/height 与 OpenAI 兼容写法的差异：BFL 原生使用 width / height 整数；APIYI 也接受 OpenAI 风格的 size: "1024x1024" 字符串，两种写法等价，二选一即可。

最佳实践

按场景选模型

旗舰终稿 + 需要联网知识 → flux-2-max；生产批量 → flux-2-pro；文字海报 / 信息图 → flux-2-flex；高吞吐实时 → flux-2-klein-9b；图像编辑首选 → flux-kontext-max 或 flux-kontext-pro。

尺寸优先 ≤ 2MP

速度和价格的最优平衡点在 1MP–2MP 之间。仅在打印 / 4K 屏幕等明确需要时再上 4MP，klein 高分辨率会显著增加单次成本。

多图融合用「图1/图2」指代

上传 image[] 时顺序作为指代依据，prompt 中显式说”图1的人物放进图2的场景，沿用图3的色彩风格”，比让模型自己推断稳得多。

结果 URL 立即下载

data[0].url 仅 10 分钟有效，且托管在 delivery-eu.bfl.ai / delivery-us.bfl.ai，CORS 默认关闭。生产服务必须代下载到自有 CDN。

文字场景锁 flex 或 max

招牌、海报、UI 截图等带文字的场景优先用 flux-2-flex（专精文字）或 flux-2-max（综合质量更高），其它模型小字仍可能糊。

联网知识用 max grounding search

需要”今天的天气”、“昨晚比赛”等实时知识时仅 flux-2-max 能用。其它模型纯靠训练数据，无法实时检索。

客户端超时 60–120 秒

APIYI 已封装好同步等待，pro / max < 15 秒到帧，但叠加排队 + 网络抖动建议客户端超时 60–120 秒。flex 较慢可设到 180 秒。

seed 固定可复现

传相同 seed + 相同其它参数可获一致结果，适合 A/B 测试与客户验收。klein 不支持 prompt_upsampling，pro/max/flex 默认关闭，按需开启。

错误码与重试

状态码	含义	处理建议
`400`	参数非法（width/height 非 16 倍数、超 4MP、prompt 超 32K tokens 等）	按尺寸约束章节校验，特别检查 16 倍数
`401`	令牌无效	检查 Bearer Token
`403`	内容审核拦截	调整 prompt 或调高 `safety_tolerance`（最高 6）
`429`	限流 / 余额不足 / active tasks 超限	指数退避重试
`5xx`	网关 / 后端错误	重试 1–2 次
超时	长尾	客户端超时 ≥ 60 秒（flex 建议 180 秒）

建议客户端：

请求超时 60–120 秒 起步（flex 模型放宽到 180 秒）
对 5xx 与 429 做 指数退避重试（建议 2 次）
拿到 data[0].url 后立即异步下载，不要等用户点击再拉
记录响应头 x-request-id 方便排查

常见问题

返回的 url 字段为什么 10 分钟就失效？

BFL 官方设计：所有结果都托管在 delivery-eu.bfl.ai / delivery-us.bfl.ai，签名 URL 有效期 10 分钟，且不开启 CORS。生产服务必须服务端代下载到自有 OSS / CDN，不能直接给浏览器渲染、也不能让用户长期访问。APIYI 网关沿用了同一套 URL 机制，行为与官方一致。

官方走异步轮询，APIYI 怎么变成同步的？

APIYI 网关替你做了 polling：你发一个标准的 OpenAI Images API 请求，网关内部代你 POST 到 BFL、轮询 polling_url 直到 Ready，再把最终的 result.sample URL 包装成 data[0].url 返回。客户端看到的就是一发请求一次响应，与 OpenAI / GPT-Image / Nano Banana 完全一致。

多参考图最多能传几张？怎么写 prompt？

FLUX.2 [pro/max/flex]：最多 8 张
FLUX.2 [klein]：最多 4 张
FLUX.1 Kontext [pro/max]：单张为主（多图融合靠拼图变通）

在 prompt 里用「图1/图2/图3」明确指代，例如”把图1的人物放进图2的场景，沿用图3的色彩风格”。也可以自然语言描述，模型理解输入图的内容能力较强。

prompt_upsampling 是干什么的？要开吗？

prompt_upsampling=true 时模型会自动扩写 / 优化你的 prompt（特别适合短 prompt）。但会改变原意，专业排版 / 品牌素材建议关闭、自由探索时可以开。限制：FLUX.2 [klein] 系列不支持，传了会被忽略。

grounding search 联网搜索具体怎么用？

仅 flux-2-max 支持。无需特殊参数，只要 prompt 里包含需要实时知识的内容，模型就会自动联网搜索后再出图。例如：

“Generate a news photo of the snowstorm hitting NYC on Dec 15, 2025”

适合”昨日比赛比分”、“实时天气”、“历史事件复刻”、“最新流行趋势”等。无联网知识的 prompt 即使打开也不会触发，按普通生图计费。

hex 色控怎么写最有效？

直接在 prompt 中写 hex 码，并用「color」/「hex」之类关键词显式标注：

A vase on a table, the color of the vase is gradient from #02eb3c to #edfa3c, the flowers have color #ff0088

或者多色品牌：

Luxury eyeshadow palette with 6 pans: top row #B76E79, #E8D5B7, #8B4789; bottom row #CD7F32, #F8F6F0, #800020

精度业内领先，无需后期调色。

结构化 JSON prompt 是什么？

FLUX.2 支持把 prompt 写成 JSON：

{
  "subject": "Mona Lisa painting by Leonardo da Vinci",
  "background": "museum gallery wall, ornate gold frame",
  "lighting": "soft gallery lighting",
  "style": "digital art, high contrast",
  "camera_angle": "eye level view",
  "composition": "centered, portrait orientation"
}

把 JSON 字符串作为 prompt 字段值传入。适合产线自动化、批量生成同模板素材。

single image 编辑端点怎么调？

走 /v1/images/edits，multipart/form-data 上传 image[] + prompt，详细参数和示例见图片编辑 API。注意：FLUX.1 Kontext 系列原生只支持单参考图；FLUX.2 系列原生支持最多 8 张。

可以直接用 OpenAI 官方 SDK 调用吗？

可以，零代码改动。把 base_url 指向 https://api.apiyi.com/v1 即可：

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.apiyi.com/v1")
resp = client.images.generate(
    model="flux-2-pro",
    prompt="...",
    size="1024x1024"
)

Node.js 的 openai 包同理。所有 FLUX 模型都按 OpenAI Images API 规范返回 data[0].url。

支持主动取消任务吗？

不支持。客户端断开连接后服务端仍会把生成跑完并照常计费。建议客户端做好超时控制，不要依赖”断连不收费”的假设。

速率限制和并发是多少？

BFL 官方对单账号限 24 active tasks，flux-kontext-max 单独限 6 active tasks。APIYI 在网关层做了池化，企业用户的并发不受单账号上限制约。如需明确 SLA / RPM 配额，请联系商务申请扩容。

webhook 回调能用吗？

BFL 官方支持 webhook_url + webhook_secret，但 APIYI 的 OpenAI 兼容封装走同步等待，未透传 webhook 字段——不需要轮询，发一发拿一发。如果业务确实需要 webhook，请联系我们说明场景，可单独开启原生异步通道。

生成失败会扣费吗？

不会。参数 400、内容审核 403、限流 429 都返回错误且不计费。只有请求实际进入模型生成阶段（即收到 200 + data[0].url）才会按张数计费。

产品基础

基础 API

图片 API

视频 API

多模态理解 API

文本 API

概述

文生图 API

图片编辑 API

历史版本

为什么选 API易的 FLUX？

OpenAI 兼容封装 · 零代码迁移

不限并发 · 突破 24 active 限制

同价或最高节省 17%

全球零门槛接入

模型生态齐全

专业服务 · 企业陪跑

核心特性

速度全档位覆盖

原生 4MP 输出

多参考图融合

联网搜索（grounding search）

精确 hex 色控制

32K tokens 长 prompt

文字渲染特化

OpenAI SDK 直连

模型定价

FLUX.2 系列（最新一代）

FLUX.1 Kontext 系列（图像编辑专用）

FLUX.1 [pro] 经典版本（历史版本，仍可调用）

技术规格

端点一览

尺寸（width / height）详解

常用尺寸

自定义尺寸约束

最佳实践

错误码与重试

常见问题

相关文档

产品基础

基础 API

图片 API

视频 API

多模态理解 API

文本 API

​概述

文生图 API

图片编辑 API

历史版本

​为什么选 API易 的 FLUX？

OpenAI 兼容封装 · 零代码迁移

不限并发 · 突破 24 active 限制

同价或最高节省 17%

全球零门槛接入

模型生态齐全

专业服务 · 企业陪跑

​核心特性

速度全档位覆盖

原生 4MP 输出

多参考图融合

联网搜索（grounding search）

精确 hex 色控制

32K tokens 长 prompt

文字渲染特化

OpenAI SDK 直连

​模型定价

​FLUX.2 系列（最新一代）

​FLUX.1 Kontext 系列（图像编辑专用）

​FLUX.1 [pro] 经典版本（历史版本，仍可调用）

​技术规格

​端点一览

​尺寸（width / height）详解

​常用尺寸

​自定义尺寸约束

​最佳实践

​错误码与重试

​常见问题

​相关文档

概述

为什么选 API易的 FLUX？

核心特性

模型定价

FLUX.2 系列（最新一代）

FLUX.1 Kontext 系列（图像编辑专用）

FLUX.1 [pro] 经典版本（历史版本，仍可调用）

技术规格

端点一览

尺寸（width / height）详解

常用尺寸

自定义尺寸约束

最佳实践

错误码与重试

常见问题

相关文档