FLUX 图像生成 API

VE2S 开放平台 · 图像生成服务
Base URL:https://cloud.ve2s.ai

FLUX 是 Black Forest Labs(BFL)推出的业界领先的图像生成模型家族，在提示词遵循、画面质量与文字渲染方面均处于第一梯队。VE2S 开放平台以 OpenAI 兼容接口 提供 FLUX 全系列模型的文生图与图像编辑能力:您无需对接 BFL 原生的异步轮询接口，一次 HTTP 请求即可同步获得生成结果，并可无缝复用 OpenAI SDK 及现有工具链。

1. 模型总览

模型 ID	定位	能力	最大分辨率	默认分辨率	默认格式
`flux-2-max`	FLUX.2 旗舰	文生图 + 图像编辑(多参考图)	400 万像素(如 2048×2048)	1024×1024	JPEG
`flux-2-pro`	FLUX.2 主力，推荐默认选择	文生图 + 图像编辑(多参考图)	400 万像素(如 2048×2048)	1024×1024	JPEG
`flux-kontext-max`	FLUX.1 Kontext 高配	文生图 + 单图编辑	约 100 万像素(固定)	1024×1024	PNG
`flux-kontext-pro`	FLUX.1 Kontext 标准	文生图 + 单图编辑	约 100 万像素(固定)	1024×1024	PNG
`flux-pro-1.1`	经典高速文生图	仅文生图	1440×1440	1024×768	JPEG

选型建议

通用生成与编辑:优先使用 flux-2-pro，质量、速度与成本均衡，是 BFL 官方推荐的默认模型。

最高质量、最难的编辑任务:使用 flux-2-max，拥有最强的编辑一致性与提示词遵循能力。

快速、大批量文生图:使用 flux-pro-1.1，单图生成通常 3–6 秒完成。

flux-kontext-pro / flux-kontext-max 为上一代编辑模型，适合存量业务平滑迁移;新项目建议直接使用 FLUX.2 系列。

2. 快速开始

2.1 接口地址与鉴权

POST https://cloud.ve2s.ai/v1/images/generations
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>

API Key 在控制台「令牌管理」中创建。请妥善保管密钥，不要在客户端代码中明文暴露。

2.2 第一个请求(cURL)

2.3 响应示例

{
  "created": 1783332729,
  "data": [
    {
      "url": "https://storage.example.com/.../sample.jpeg?se=...&sig=...",
      "seed": 2357622065
    }
  ]
}

重要:url 为带时效签名的临时下载链接，平台不承诺其长期有效。请在拿到响应后立即下载图片并转存至您自己的存储，不要将该链接直接持久化或分发给终端用户。

2.4 使用 OpenAI SDK(Python)

建议将客户端超时设置为 120 秒以上。接口为同步返回，典型耗时见 7.1 性能参考。

3. 请求参数

3.1 通用参数

参数	类型	必填	说明
`model`	string	是	模型 ID，见模型总览
`prompt`	string	是	提示词。支持中英文，英文提示词效果通常更稳定
`size`	string	否	输出尺寸，格式 `宽x高`(如 `1024x1024`)。各模型的取值范围与行为不同，详见第 4 节
`image`	string / string[]	否	图像编辑的输入图。支持纯 Base64、`data:image/...;base64,` 前缀或公网可访问的图片 URL;FLUX.2 系列可传入数组以使用多参考图。详见第 5 节
`seed`	integer	否	随机种子。实际使用的种子会在响应 `data[].seed` 中返回。相同种子不保证严格复现同一图像，请勿将像素级复现作为业务依赖
`output_format`	string	否	输出图片格式:`jpeg` / `png` / `webp`。默认值见模型总览表
`prompt_upsampling`	boolean	否	是否由模型自动扩写提示词以获得更有创意的结果，默认 `false`(`flux-pro-1.1`、Kontext 系列支持)
`safety_tolerance`	integer	否	内容安全容忍度，数值越大越宽松，默认 `2`。`flux-pro-1.1` 与 Kontext 系列取值 0–6，FLUX.2 系列取值 0–5

注意事项

n(单次生成张数)参数当前不生效，每次请求固定返回 1 张图片。如需多张，请并发发起多个请求。

response_format 参数当前不生效，返回格式固定为临时下载链接(url)，不支持 b64_json。

aspect_ratio 顶层参数当前不生效，请统一通过 size 控制输出比例(见第 4 节)。

请求体中的其余 OpenAI 标准字段(如 quality、style)对 FLUX 模型无效，将被忽略。

3.2 响应字段

字段	类型	说明
`created`	integer	任务完成时间(Unix 秒级时间戳)
`data`	array	生成结果列表(当前固定 1 个元素)
`data[].url`	string	图片临时下载链接，不保证长期有效，请立即转存
`data[].seed`	integer	本次生成实际使用的随机种子

4. 各模型尺寸与分辨率规格

三个模型家族对 size 的处理逻辑并不相同，请务必按家族分别对待。

4.1 FLUX.2 系列(`flux-2-max` / `flux-2-pro`)

项目	规格
像素总量上限	400 万像素(宽 × 高 ≤ 2048 × 2048)
单边最小值	64 px
尺寸步进	16 px 的整数倍;非 16 倍数时自动向下取整(如请求 `1000x1000` 实际输出 `992x992`)，不报错
宽高比	任意(在像素总量限制内自由组合)
默认尺寸	1024×1024
超出限制	宽 × 高超过 400 万像素时返回 `422` 错误

官方建议:200 万像素以内可获得最佳的画质与速度平衡。

常用尺寸速查(FLUX.2)

宽高比	标准档	高清档
1:1	1024×1024	2048×2048
4:3	1152×864	2048×1536
3:4	864×1152	1536×2048
16:9	1280×720	1920×1088
9:16	720×1280	1088×1920
3:2	1536×1024	2400×1600
21:9	1344×576	2016×864

4.2 FLUX.1 Kontext 系列(`flux-kontext-max` / `flux-kontext-pro`)

Kontext 模型的输出分辨率固定在约 100 万像素，size 参数仅用于表达期望的宽高比——模型会在 1MP 总量内自动匹配最接近的输出尺寸(边长为 32 px 的整数倍)，因此实际输出尺寸与请求值不一定相等。

项目	规格
像素总量	固定约 100 万像素，不可调
宽高比范围	21:9 ~ 9:21;超出范围时自动收敛到最近的合法比例(不报错)
尺寸步进	输出边长为 32 px 的整数倍
默认尺寸	1024×1024(不传 `size` 时)

实测对照(Kontext)

请求 `size`	实际输出	说明
`1024x1024`	1024×1024	1:1 直接命中
`1792x1024`(7:4)	1328×800	按宽高比缩放至 1MP
`2016x864`(21:9)	1568×672	横向极限比例
`3072x1024`(3:1，越界)	1568×672	自动收敛为 21:9

如需 2K/4K 级别的高分辨率输出，请改用 FLUX.2 系列。

4.3 FLUX 1.1 Pro(`flux-pro-1.1`)

项目	规格
宽/高取值范围	256 ~ 1440 px
尺寸步进	必须为 32 px 的整数倍，否则返回 `422` 错误
默认尺寸	1024×768(不传 `size` 时)
超出限制	任一边 < 256、> 1440 或非 32 倍数，均返回 `422` 错误(严格校验，不自动取整)

常用尺寸速查(FLUX 1.1 Pro)

宽高比	推荐尺寸
1:1	1024×1024(最大 1440×1440)
4:3	1280×960
3:4	960×1280
16:9	1024×576
9:16	576×1024
3:2	1344×896
21:9	1344×576

5. 图像编辑

FLUX.2 系列与 Kontext 系列支持以自然语言指令编辑输入图像:改色、换背景、增删元素、风格迁移、多图合成等。flux-pro-1.1 不支持图像编辑。

5.1 输入图格式

image 字段支持三种形式:

纯 Base64 字符串(推荐，最稳定)

Data URI:data:image/jpeg;base64,<...>

公网图片 URL:平台会拉取该地址，请确保链接可公开访问且未过期

5.2 单图编辑示例(Kontext / FLUX.2 通用)

Python(标准库，注意 Base64 字符串不要包含换行):

5.3 多参考图编辑(仅 FLUX.2 系列)

image 传入数组即可携带多张参考图，模型可同时参考多张图片的主体、风格与构图进行合成。API 最多支持 8 张参考图;单张参考图建议不超过 400 万像素(超出会被自动缩放)。

{
  "model": "flux-2-max",
  "prompt": "Place the product from the first image next to the logo from the second image on a wooden table",
  "image": ["<BASE64_IMAGE_1>", "<BASE64_IMAGE_2>"],
  "size": "1024x1024"
}

Kontext 系列同样支持 image 数组多参考图(最多 4 张)，但该能力为实验性，效果不做保证;生产环境的多图合成请优先使用 FLUX.2 系列(最多 8 张)。

5.4 编辑时的尺寸行为

FLUX.2 系列:可同时传 size 指定输出尺寸，规则与文生图一致(≤4MP)。

Kontext 系列:输出固定约 1MP，宽高比默认贴近输入图，也可用 size 表达目标比例。

5.5 兼容接口:`POST /v1/images/edits`

平台同时兼容 OpenAI 的 multipart/form-data 编辑接口，image 作为文件字段上传，响应结构与 /v1/images/generations 相同。适合已按 OpenAI images/edits 规范对接的存量代码:

新项目建议统一使用 JSON 版 /v1/images/generations。

6. 错误处理

接口使用标准 HTTP 状态码，错误响应结构如下:

{
  "error": {
    "message": "具体错误描述 (request id: xxxx)",
    "type": "rix_api_error",
    "param": "",
    "code": "bad_response_status_code"
  }
}

HTTP 状态码	含义	常见原因与处理
401	鉴权失败	API Key 缺失、错误或已禁用
403	无权访问	令牌无该模型权限或分组不匹配
422	参数校验失败	尺寸越界 / 非法步进 / 像素总量超限，`message` 中包含具体的字段与限制值
429	触发限流	降低并发或稍后重试，建议指数退避
5xx	服务暂时不可用	可安全重试;持续失败请联系技术支持并附上 `request id`

422 实例(便于排错)

flux-pro-1.1 请求 1000x1000:Input should be a multiple of 32

flux-pro-1.1 请求 2048x2048:Input should be less than or equal to 1440

flux-2-pro 请求 2560x2560:Total pixels (6553600) exceeds maximum of 4194304 (4MP)

7. 最佳实践

7.1 性能参考

实测单请求典型耗时(1024×1024，同步返回):

模型	典型耗时
`flux-pro-1.1`	3 – 6 秒
`flux-kontext-pro` / `flux-kontext-max`	8 – 12 秒
`flux-2-pro`	8 – 20 秒
`flux-2-max`	12 – 40 秒

大尺寸(接近 4MP)与多参考图会显著增加耗时，请将客户端超时设置为 120 秒以上，批量场景建议 300 秒。

7.2 集成清单

及时转存图片:结果链接为临时签名地址，平台不承诺长期有效，拿到响应后立即下载并上传至自有存储。

提示词:描述"画面里有什么"，而非"不要什么"(FLUX 不支持负面提示词);编辑时明确说明"保持其余部分不变"可显著提升一致性。

精确色彩:FLUX.2 支持在提示词中直接使用十六进制色号(如 background color #1a73e8)，适合品牌物料。

文字渲染:需要在图中呈现的文字，请用引号在提示词中明确给出。

重试策略:仅对 429 / 5xx 重试;422 属于参数错误，重试无效，请先修正参数。

并发生成:n 参数不生效，多图需求请并发多个请求实现。

8. FAQ

Q:返回的图片链接可以直接给到终端用户吗?
不建议。链接为带时效签名的临时地址，平台不承诺其长期有效，随时可能因存储策略调整而失效，请务必转存后再分发。

Q:为什么我请求了 1000x1000，FLUX.2 返回的是 992×992?
FLUX.2 的输出边长必须是 16 的整数倍，平台会自动向下取整，属于预期行为。如需精确尺寸，请直接传 16 倍数的值。

Q:为什么 Kontext 输出的分辨率和我传的 size 不一致?
Kontext 的输出像素总量固定在约 100 万，size 仅决定宽高比。需要 2K 及以上输出请使用 FLUX.2 系列。

Q:支持流式返回或异步任务吗?
当前接口为同步模式，连接保持至生成完成后一次性返回，无需轮询。

Q:一次能生成几张图?
每次请求固定返回 1 张，n 参数暂不生效;多张需求请并发请求。

本文档基于 Black Forest Labs 官方规格及 VE2S 平台编写。模型能力与限制如有更新，以最新版本文档为准。

FLUX 图像生成 API

1. 模型总览#

2. 快速开始#

2.1 接口地址与鉴权#

2.2 第一个请求(cURL)#

2.3 响应示例#

2.4 使用 OpenAI SDK(Python)#

3. 请求参数#

3.1 通用参数#

3.2 响应字段#

4. 各模型尺寸与分辨率规格#

4.1 FLUX.2 系列(flux-2-max / flux-2-pro)#

4.2 FLUX.1 Kontext 系列(flux-kontext-max / flux-kontext-pro)#

4.3 FLUX 1.1 Pro(flux-pro-1.1)#

5. 图像编辑#

5.1 输入图格式#

5.2 单图编辑示例(Kontext / FLUX.2 通用)#

5.3 多参考图编辑(仅 FLUX.2 系列)#

5.4 编辑时的尺寸行为#

5.5 兼容接口:POST /v1/images/edits#

6. 错误处理#

7. 最佳实践#

7.1 性能参考#

7.2 集成清单#

8. FAQ#