获取 API Key 获取 API
文档

Flux 2.0 图像生成

- 异步处理模式,提交后返回任务 ID

  • 支持文生图、图生图和多参考图融合

  • 支持 Flex、Pro、Max 三种模型,最高输出 4MP 图像

请求示例

curl --request POST \
  --url https://api.openveer.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-2-pro",
    "prompt": "一只蓝色的猫在草地上",
    "resolution": "2MP",
    "size": "16:9",
    "output_format": "jpeg"
  }'

响应示例

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
    }
  ]
}

支持的模型

模型名 说明
flux-2-flex 支持精细控制,可调整采样步数和提示词引导强度
flux-2-pro 兼顾速度与质量,适合通用生产工作流
flux-2-max 最高质量版本,适合对图像质量要求较高的场景

除标注为 Flex 专有的参数外,下列参数和像素限制均适用于以上三种模型。

Authorizations

Authorization string

所有接口均需要使用 Bearer Token 进行认证。

获取 API Key:

访问 API Key 管理页面 获取您的 API Key。

使用时在请求头中添加:

Authorization: Bearer YOUR_API_KEY

Body

model string

模型名称:

  • flux-2-flex - 支持精细控制的 Flex 模型
  • flux-2-pro - 通用 Pro 模型
  • flux-2-max - 最高质量的 Max 模型
prompt string

图像生成或编辑的文本描述。

resolution string

输出分辨率档位:

  • 1MP
  • 2MP(默认)
  • 3MP
  • 4MP

这里的 1MP 等于 1,048,576 像素。

兼容旧别名:512 / 512P / 1M 等价于 1MP,1K / 1024 等价于 2MP,2K / 2048 等价于 3MP,4K 等价于 4MP。其他值会导致任务失败。

实际输出尺寸还取决于 size。

size string

输出图像的宽高比或像素尺寸。

size 也支持 auto:传入 image_urls 时,会沿用参考图的宽高比,并保持当前 resolution 档位;未传参考图时按默认 1:1 处理。

支持以下尺寸选项:

  • 1:1 - 方形(默认)
  • 4:3 - 横向
  • 3:4 - 纵向
  • 16:9 - 宽屏
  • 9:16 - 竖屏
  • 3:2 - 经典横向
  • 2:3 - 经典纵向
  • 21:9 - 超宽屏
  • 9:21 - 超竖屏
  • auto - 跟随参考图比例

也可以传入 "宽x高" 格式的像素串,例如 "1024x1536"。像素串优先于 resolution 和宽高比。

width integer

精确输出宽度,单位为像素。必须与 height 成对传入,每项不得小于 64;只传其中一项会导致任务失败。

width 和 height 的优先级最高;同时传入时,会覆盖 resolution 和 size。

height integer

精确输出高度,单位为像素。必须与 width 成对传入,每项不得小于 64;只传其中一项会导致任务失败。

输出总像素不得超过 4MP,即 width × height ≤ 4,194,304。

image_urls array

参考图像列表,用于图生图或多参考图融合。

限制:

  • 最多支持 8 张图片
  • 支持公网可访问的 URL 或 Base64 输入
  • 输出图像与所有参考图的总像素不得超过 9MP
output_format string

输出图片的编码格式,支持 jpeg、png 和 webp。

n integer

每次生成的图片张数。仅允许传入 1;需要多张图片时,请并发提交多个任务。

seed integer

随机种子。固定种子并保持其他参数一致时,可以复现相同结果;不传时随机生成。

prompt_upsampling boolean

是否启用提示词增强:

  • true - 启用
  • false - 禁用(默认)

显式传入 false 可关闭提示词改写。

safety_tolerance integer

内容审核宽松度,取值范围为 0–5。数值越高,审核越宽松。

steps integer

采样步数,仅 flux-2-flex 支持。取值范围为 1–50;数值越高,通常细节越多、生成时间越长。

guidance number

提示词引导强度,仅 flux-2-flex 支持。取值范围为 1.5–10;数值越高,生成结果通常越贴近提示词。

分辨率对照表

比例 1MP 2MP(默认) 3MP 4MP
1:1 1024×1024 1440×1440 1536×1536 2048×2048
4:3 1152×864 1664×1248 1824×1360 2336×1760
3:4 864×1152 1248×1664 1360×1824 1760×2336
16:9 1344×752 1920×1072 2048×1152 2720×1536
9:16 752×1344 1072×1920 1152×2048 1536×2720
3:2 1248×832 1728×1152 1872×1248 2496×1664
2:3 832×1248 1152×1728 1248×1872 1664×2496
21:9 1504×640 2176×928 2304×992 3072×1312
9:21 640×1504 928×2176 992×2304 1312×3072

尺寸参数优先级为:成对的 width + height → size 像素串 → resolution + size 宽高比 → 默认 2MP + 1:1。

使用场景示例

基础文生图

{
  "model": "flux-2-pro",
  "prompt": "赛博朋克风格的城市夜景,霓虹灯反射在湿润街道上",
  "resolution": "1MP",
  "size": "16:9"
}

最高质量生成

{
  "model": "flux-2-max",
  "prompt": "清晨薄雾中的雪山与湖泊,细节丰富,电影感",
  "resolution": "4MP",
  "size": "3:2"
}

精确像素尺寸

{
  "model": "flux-2-pro",
  "prompt": "一只蓝色的猫",
  "width": 1024,
  "height": 1536
}

多参考图融合

{
  "model": "flux-2-pro",
  "prompt": "把图 1 的人物放进图 2 的场景,统一光照和色调",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/scene.jpg"
  ],
  "resolution": "2MP",
  "size": "16:9"
}

Flex 精细控制

{
  "model": "flux-2-flex",
  "prompt": "极简风格海报,大标题写 SUMMER SALE,下方小字写 50% OFF",
  "resolution": "3MP",
  "size": "3:4",
  "steps": 50,
  "guidance": 6.5
}

Response

提交成功后,data 为数组,任务 ID 位于 data[0].task_id。

code integer

响应状态码。

data array
返回数据数组。
status string

提交状态。成功提交时为 submitted。

task_id string

任务唯一标识符,用于查询任务状态和结果。

查询任务结果

任务为异步处理。使用提交响应中的 task_id 请求以下接口,直到状态变为 completed 或 failed:

curl --request GET \
  --url https://api.openveer.com/v1/tasks/task_01KFG5BBFNK1YQDTJDZY0P0QT2 \
  --header 'Authorization: Bearer <token>'

任务状态包括:

状态 说明
submitted / pending 任务已受理或正在排队,请继续轮询
processing 图像正在生成,请继续轮询
completed 任务完成,可从 result.images[0].url[0] 获取图片 URL
failed 任务失败,可查看 data.error.message;任务费用会全额退还

完成响应示例:

{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.openveer.com/f/image/xxxxxxxx-flux-2.jpeg"
          ],
          "expires_at": 1785220083
        }
      ]
    }
  }
}

result.images[].url 是字符串数组。本系列每次固定生成 1 张图片,请读取 url[0]。图片 URL 的有效期以同一对象中的 expires_at Unix 时间戳为准,请在到期前保存生成结果。

参数错误与失败响应

模型参数无效时,提交接口仍会返回 HTTP 200 和 task_id。请持续轮询,任务随后会进入 failed 状态,并在 data.error.message 中返回具体原因。失败任务会全额退款。

{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "`steps` must be between 1 and 50 (got 0)"
    }
  }
}

error.code 固定为 task_failed,具体失败原因请读取 error.message。

注意事项

  1. 尺寸限制:输出图像不得超过 4MP,且宽、高均不得小于 64 像素。
  2. 总像素限制:输出图像与所有参考图的总像素不得超过 9MP。
  3. 参考图要求:最多支持 8 张参考图,可使用公网可访问的图片 URL 或 Base64 输入。
  4. 固定生成张数:n 默认且只能为 1。
  5. 提示词增强:prompt_upsampling 默认为 false;显式传入 false 可关闭提示词改写。
  6. Flex 专有参数:steps 和 guidance 仅适用于 flux-2-flex。
  7. 异步任务:提交成功后,请轮询 /v1/tasks/{task_id} 获取最终结果。
  8. 结果链接:图片 URL 的有效期以响应中的 expires_at 为准。
  9. 异步参数错误:非法模型参数不会在提交时同步返回 4xx;必须轮询到 failed 并读取 data.error.message。