-
支持文生图、图生图和多参考图融合
-
支持 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"
}'import requests
url = "https://api.openveer.com/v1/images/generations"
payload = {
"model": "flux-2-pro",
"prompt": "一只蓝色的猫在草地上",
"resolution": "2MP",
"size": "16:9",
"output_format": "jpeg"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())const url = "https://api.openveer.com/v1/images/generations";
const payload = {
model: "flux-2-pro",
prompt: "一只蓝色的猫在草地上",
resolution: "2MP",
size: "16:9",
output_format: "jpeg"
};
const headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));响应示例
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
}
]
}{
"error": {
"code": 401,
"message": "身份验证失败,请检查您的 API 密钥",
"type": "authentication_error"
}
}{
"error": {
"code": 402,
"message": "账户余额不足,请充值后再试",
"type": "payment_required"
}
}支持的模型
| 模型名 | 说明 |
|---|---|
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_KEYBody
model string模型名称:
flux-2-flex- 支持精细控制的 Flex 模型flux-2-pro- 通用 Pro 模型flux-2-max- 最高质量的 Max 模型
prompt string图像生成或编辑的文本描述。
resolution string输出分辨率档位:
1MP2MP(默认)3MP4MP
这里的 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 arraystatus 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。
注意事项
- 尺寸限制:输出图像不得超过 4MP,且宽、高均不得小于 64 像素。
- 总像素限制:输出图像与所有参考图的总像素不得超过 9MP。
- 参考图要求:最多支持 8 张参考图,可使用公网可访问的图片 URL 或 Base64 输入。
- 固定生成张数:
n默认且只能为1。 - 提示词增强:
prompt_upsampling默认为false;显式传入false可关闭提示词改写。 - Flex 专有参数:
steps和guidance仅适用于flux-2-flex。 - 异步任务:提交成功后,请轮询
/v1/tasks/{task_id}获取最终结果。 - 结果链接:图片 URL 的有效期以响应中的
expires_at为准。 - 异步参数错误:非法模型参数不会在提交时同步返回 4xx;必须轮询到
failed并读取data.error.message。