获取 API Key 获取 API
文档

Flux Kontext 图像生成

- 异步处理模式,返回任务ID用于后续查询

  • Pro 和 Max 均支持文本生成图片与参考图编辑
  • 生成结果中的 expires_at 表示图片链接的过期时间

请求示例

curl --request POST \
  --url https://api.openveer.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-pro",
    "prompt": "把头发变成蓝色",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "16:9",
    "output_format": "png"
  }'

响应示例

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

支持的模型

模型名 说明
flux-kontext-pro Flux Kontext Pro 图像生成与编辑模型
flux-kontext-max Flux Kontext Max 高质量图像生成与编辑模型

Authorizations

Authorization string

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

获取 API Key:

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

使用时在请求头中添加:

Authorization: Bearer YOUR_API_KEY

Body

model string

模型名称

  • flux-kontext-pro - Kontext Pro 图像生成与编辑模型
  • flux-kontext-max - Kontext Max 高质量图像生成与编辑模型
prompt string

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

image_urls array

参考图片列表。不传时为文生图,传入时为图片编辑。

限制:

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

如果参考图 URL 无法公开访问,任务可能只返回 temporarily unavailable dependency。遇到该提示时,请优先检查防盗链、访问权限和签名是否过期。

size string

图像宽高比。也可以传入像素串,例如 1024x1536;Kontext 会将其映射到最接近的支持比例,不保证精确输出该像素尺寸。

支持的宽高比和自动模式:

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

当 size 设置为 auto 时,如果提供了 image_urls,输出将跟随参考图的宽高比;如果没有参考图,则按默认的 1:1 处理。

Kontext 不支持 width 或 height,传入任一字段都会导致任务失败;请使用 size 控制宽高比。resolution 对 Kontext 不生效,输出恒定在约 1MP。

output_format string

输出图片的编码格式

  • png - PNG 格式(默认)
  • jpeg - JPEG 格式
  • webp - WebP 格式
response_format string

OpenAI 兼容响应形态字段,仅支持 url 或 b64_json。它不会改变图片编码;同时传入时,以 output_format 为准。

n integer

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

seed integer

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

prompt_upsampling boolean

是否启用提示词增强

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

显式设置为 false 可关闭提示词改写。

safety_tolerance integer

安全容忍度

取值范围:0-6,数值越高越宽松

实际输出尺寸

比例 实际输出尺寸
1:1 1024×1024
4:3 1184×880
3:4 880×1184
16:9 1392×752
9:16 752×1392
3:2 1248×832
2:3 832×1248
21:9 1568×672
9:21 672×1568

使用场景示例

图片编辑(带输入图片)

{
    "model": "flux-kontext-pro",
    "prompt": "把背景换成海滩",
    "image_urls": ["https://example.com/photo.jpg"],
    "size": "16:9",
    "output_format": "png"
}

纯文生图(无输入图片)

{
    "model": "flux-kontext-max",
    "prompt": "一只蓝色的猫",
    "size": "1:1",
    "seed": 12345
}

多参考图编辑

{
    "model": "flux-kontext-max",
    "prompt": "把图一的人物放进图二的场景,并统一光照",
    "image_urls": [
        "https://example.com/person.jpg",
        "https://example.com/scene.jpg"
    ],
    "size": "4:3"
}

Response

code integer

响应状态码

data array
返回数据数组
status string

任务状态

  * submitted - 已提交
task_id string

任务唯一标识符,用于后续查询任务结果

查询任务结果

提交成功后,通过 GET /v1/tasks/{task_id} 轮询任务状态,详见 任务查询接口。

成功响应示例

{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "created": 1785133674,
    "completed": 1785133683,
    "actual_time": 9,
    "estimated_time": 15,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.openveer.com/f/image/xxxxxxxx-flux-kontext.png"
          ],
          "expires_at": 1785220083
        }
      ]
    }
  }
}

取图路径:data.result.images[0].url[0]。expires_at 是该链接的 Unix 过期时间戳,请在过期前保存图片。

任务状态

状态 含义
submitted / pending 任务已受理或正在排队,继续轮询
processing 生成中,继续轮询
completed 生成成功,结果位于 result.images
failed 生成失败,查看 data.error.message;任务费用会全额退还

参数错误与失败响应

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

{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "width/height are not supported by flux-kontext-pro"
    }
  }
}

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

注意事项

  1. 异步处理:提交后返回 task_id,需要轮询 /v1/tasks/{task_id} 获取结果。
  2. 参考图要求:最多支持 4 张参考图,可使用公网可访问的图片 URL 或 Base64 输入;输出与全部参考图合计不得超过 9MP。
  3. 尺寸规则:默认比例为 1:1。width / height 会导致任务失败,resolution 不改变约 1MP 的输出,像素格式的 size 会映射到最接近的支持比例。
  4. 生成张数:n 默认且只能为 1。
  5. 提示词改写:显式设置 prompt_upsampling: false 可关闭提示词改写。
  6. 结果链接:图片 URL 的有效期以对应的 expires_at Unix 时间戳为准,请及时保存。
  7. 异步参数错误:非法模型参数不会在提交时同步返回 4xx;必须轮询到 failed 并读取 data.error.message。