FLUX 3 Image 图像生成

信息

本接口为异步接口。提交成功后返回 task_id，请通过任务查询获取状态与图片。等待至 completed 或 failed 后停止轮询。4k 生成可能需要几分钟，建议将整体等待超时设为 10 分钟。

请求示例

curl --request POST \
  --url https://api.openveer.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-3-image",
    "prompt": "黎明时雾气笼罩的沿海公路，超宽幅电影镜头，一辆开着车灯的复古汽车",
    "aspect_ratio": "21:9",
    "resolution": "2k"
  }'

import requests

response = requests.post(
    "https://api.openveer.com/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "flux-3-image",
        "prompt": "黎明时雾气笼罩的沿海公路，超宽幅电影镜头，一辆开着车灯的复古汽车",
        "aspect_ratio": "21:9",
        "resolution": "2k"
    }
)
print(response.json())

const response = await fetch("https://api.openveer.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "flux-3-image",
    prompt: "黎明时雾气笼罩的沿海公路，超宽幅电影镜头，一辆开着车灯的复古汽车",
    aspect_ratio: "21:9",
    resolution: "2k"
  })
});
console.log(await response.json());

响应示例

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

请求头

Authorization string

Bearer 认证，格式为 Bearer <token>，其中 <token> 为你的 OpenVeer API Key。

请求参数

model string

固定为 flux-3-image。

prompt string

文生图的画面描述，或图片编辑指令。不支持负面提示词，请正面描述希望生成的画面。

支持在 prompt 中使用标签和 bbox JSON 指定布局或局部编辑区域，详见下方示例。

image_urls string[]

参考图片列表，最多支持 10 张。支持公网可访问的 HTTP(S) URL 或 Base64 输入。

不传时为文生图；传入一张时可进行单图编辑，传入多张时可进行多图参考。

aspect_ratio string

输出宽高比。支持：

21:9、2:1、16:9、3:2、7:5、4:3、5:4、1:1、4:5、3:4、5:7、2:3、9:16、1:2、9:21 或 auto。

兼容 16x9 形式的比例写法。使用 auto 时：

编辑或多图参考：跟随第一张参考图的画幅。
纯文生图：根据提示词决定；未确定画幅时使用 1:1。

size string

宽高比的兼容参数，可替代 aspect_ratio，取值与其相同。建议只使用其中一个字段。

不支持 1024x1024 等像素尺寸，传入会返回 HTTP 400。请通过 resolution 选择输出分辨率。

resolution string

输出分辨率档位，支持 768sq、1k、1.5k、2k、4k，大小写不敏感，768 等同于 768sq。

该参数决定计费档位。不传时按 1k 生成和计费；传入 3k 等不支持的值会返回 HTTP 400。

safety_tolerance integer

内容安全容忍度，取值为 0–4，0 最严格。

grounding boolean

是否允许在生成前进行网页或图片检索。传入 false 可关闭。

必须为布尔值，不能传字符串 "false" 或 "true"。

n integer

每次请求生成 1 张图片，仅支持 1。需要多张时请分别提交任务，传入大于 1 的值会返回 HTTP 400。

不支持的参数

以下参数传入后会返回 HTTP 400，不会静默忽略：

width、height
像素尺寸形式的 size，例如 1024x1024
seed、steps、guidance
output_format、negative_prompt、prompt_upsampling、mask_url

需要更高分辨率时使用 resolution，需要特定画幅时使用 aspect_ratio。

编辑参考图

{
  "model": "flux-3-image",
  "prompt": "将图中的汽车改为红色，保留原有道路、背景和光照",
  "image_urls": ["https://example.com/car.jpg"],
  "aspect_ratio": "auto",
  "resolution": "2k"
}

请将示例 URL 替换为公网可访问的图片地址。多图参考时，在 image_urls 中提供多个地址，总数不超过 10 张。

多图参考

编辑、局部编辑和布局都使用本页同一接口及模型，按 resolution 计费。参考图按顺序编号：第一张为 ref_image_0，第二张为 ref_image_1；提示词中也可直接使用 Image 1 / Image 2。

{
  "model": "flux-3-image",
  "prompt": "将 Image 1 转换成 Image 2 的风格。",
  "image_urls": [
    "https://example.com/subject.jpg",
    "https://example.com/style.jpg"
  ],
  "aspect_ratio": "auto"
}

局部编辑（bounding box）

先在 prompt 中用自然语言描述编辑指令，并使用 <标签> 指代元素（例如 <car_1>）；随后在同一个字符串中附加 JSON 数组，每个对象描述一个框。bbox 不是独立的请求参数。

字段	说明
`id`	与提示词中的标签对应，不包含尖括号。
`from`	元素来源，例如 `ref_image_0`；新绘制或重绘的元素使用 `null`。
`src_bbox`	元素在原图中的框；`from` 为 `null` 时，此字段也为 `null`。
`tgt_bbox`	元素在输出图中的框；与 `src_bbox` 相同表示原地保留，不同表示移动。
`desc`	描述元素需要如何修改或保持什么样。

所有框字段（src_bbox、tgt_bbox、bbox）均使用 [上, 左, 下, 右]，即 [y1, x1, y2, x2]。采用 0–1000 归一化坐标：左上角为 [0,0]，右下角为 [1000,1000]，不是实际像素坐标。

下面示例将框内汽车改为红色，并描述需要保留的背景。URL 和框位置仅为示例，请按实际图片替换。

{
  "model": "flux-3-image",
  "prompt": "在 <ref_image_0> 中，将汽车 <car_1> 改为红色，保留背景 <background_1>。 [{\"id\":\"car_1\",\"from\":null,\"src_bbox\":null,\"tgt_bbox\":[250,300,750,800],\"desc\":\"红色汽车，保持原有形状和朝向。\"},{\"id\":\"background_1\",\"from\":\"ref_image_0\",\"src_bbox\":[0,0,1000,1000],\"tgt_bbox\":[0,0,1000,1000],\"desc\":\"保留原有道路、背景和光照。\"}]",
  "image_urls": [
    "https://example.com/car.jpg"
  ],
  "aspect_ratio": "auto",
  "resolution": "2k"
}

移动元素

以下对象可放入提示词末尾的 bbox 数组：from 指定原图，src_bbox 是原位置，tgt_bbox 是新位置。自然语言指令中同时使用对应的 <knight_1> 标签。

{
  "id": "knight_1",
  "from": "ref_image_0",
  "src_bbox": [
    500,
    150,
    850,
    350
  ],
  "tgt_bbox": [
    194,
    55,
    544,
    255
  ],
  "desc": "一只迷你灰色钩针骑士玩偶。"
}

文生图布局

不传参考图时也可以指定布局，每个框使用 id、bbox、desc。请显式传入 aspect_ratio，坐标网格会随画幅拉伸。

{
  "model": "flux-3-image",
  "aspect_ratio": "1:1",
  "prompt": "极简插画：黑色奔跑人物剪影 <silhouette_1>，背景为纯黄绿色 <background_1>。 [{\"id\":\"background_1\",\"bbox\":[0,0,1000,1000],\"desc\":\"带有轻微纸张纹理的荧光黄绿色背景。\"},{\"id\":\"silhouette_1\",\"bbox\":[150,150,850,850],\"desc\":\"带点状纹理的黑色奔跑人物剪影。\"}]"
}

使用注意

bbox JSON 是 prompt 字符串的一部分。手写请求 JSON 时，内部双引号需要转义为 \"；使用 SDK 或 JSON 序列化方法可自动完成转义。
需要保留的区域也应列出，并在 desc 中说明保留要求。
提示词中的元素标签必须与 JSON 的 id 一一对应；<ref_image_0> 等参考图标识用于指向输入图片。
本模型没有 mask 参数，也不支持 mask_url；传入 mask_url 会返回 HTTP 400。bbox 编辑不使用蒙版上传参数。

提交响应

code integer

响应状态码，成功为 200。

data array

任务提交结果。

status string

提交成功时为 submitted，不代表生成完成。

task_id string

任务 ID，用于查询任务状态与结果。

查询任务结果

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

成功响应示例（图片 URL 为占位示例）：

{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.jpg"]
        }
      ]
    }
  }
}

从 data.result.images[0].url 数组读取图片链接。如果任务状态为 failed，请检查返回的错误信息，不要继续等待图片。

分辨率与计费

按张计费，单价仅由 resolution 决定，与宽高比、参考图张数无关，参考图不额外加价。

分辨率档位	输出规模参考
`768sq`	约 768×768
`1k`（默认）	约 1MP
`1.5k`	约 2MP
`2k`	约 4MP
`4k`	约 16MP

输出规模为近似参考，实际像素尺寸以返回图片为准。各档价格以模型定价为准。

任务失败或被内容审核拦截时全额退款。

常见参数错误

请求	结果与处理方式
`resolution: "3k"`	HTTP 400，改用支持的 5 种档位之一
`size: "1024x1024"`	HTTP 400，使用宽高比并通过 `resolution` 选择分辨率
`n: 2`	HTTP 400，每次请求只生成 1 张图片
11 张参考图	HTTP 400，最多提供 10 张
`grounding: "false"`	HTTP 400，改为布尔值 `false`