获取 API Key 获取 API
文档

GPT-Image-2.5 图像生成

- 提供 gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 两种模型

  • 异步处理模式,返回 task_id 用于后续查询
  • 支持文生图与最多 16 张参考图的图像编辑
  • 支持 15 种比例、精确像素尺寸以及 1K / 2K / 4K 分辨率
  • 支持 low / medium / high / xhigh / max 五档质量
信息

如何选择模型: gpt-image-2.5-flare 速度更快,适合日常高质量出图、批量生成和快速原型;gpt-image-2.5-sunburst 更强调编辑精度,适合成品级商品图、投放创意和多轮精细编辑。两者计费标准相同。

请求示例

curl --request POST \
  --url https://api.openveer.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "雨天窗边温暖舒适的阅读角,暖色台灯,电影感光影",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

响应示例

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

认证

Authorization string

所有接口均使用 Bearer Token 认证。访问 API Key 管理页面 获取密钥。

Authorization: Bearer YOUR_API_KEY

模型选择

模型 特点 适用场景
gpt-image-2.5-flare 默认款,生成速度快 社媒内容、商品图、视觉搜索、快速原型、大批量生成
gpt-image-2.5-sunburst 编辑精度优先 投放级创意、成品级商品图、多轮精细编辑

两个模型的单价和相同参数下的 token 消耗一致,选择时只需考虑速度与质量取舍。

与 gpt-image-2 相比,GPT-Image-2.5 新增 xhigh 和 max 两个质量档位;medium 与 high 的输出 token 消耗约为上一代同名档位的四分之一。

请求参数

model string

图像生成模型名称。可选值:

  • gpt-image-2.5-flare
  • gpt-image-2.5-sunburst
prompt string

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

支持中英文。建议说明主体、场景、构图、风格、光线以及需要保留或修改的内容。

size string

输出图像的比例或精确像素尺寸。

支持:

  • auto:由模型根据提示词或参考图决定
  • 比例名:1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、21:9、9:21、3:1、1:3
  • 精确像素:例如 1600x1200

提示



图生图时建议不传 size,系统会根据输入图比例和 resolution 自动计算输出尺寸。

resolution string

分辨率档位,与比例形式的 size 配合决定实际输出像素。

  • 1k(默认)
  • 2k
  • 4k

当 size 使用精确像素格式时,此字段会被忽略。

quality string

图片质量档位。

  • low
  • medium
  • high
  • xhigh
  • max
  • auto(默认,由模型运行时决定)

警告



xhigh 和 max 仅 GPT-Image-2.5 支持。将其传给 gpt-image-2 会同步返回 400,不会自动降级。

n integer

生成图片数量,取值范围为 1 \~ 4。

必须传入数字,不要使用字符串。

output_format string

输出文件格式。

  • png(默认,支持透明背景)
  • jpeg
  • webp(支持透明背景)
output_compression integer

输出压缩强度,范围为 0 \~ 100,仅对 jpeg 和 webp 生效。

background string

背景模式。可选值:transparent、opaque、auto。

警告



background: "transparent" 只能与 output_format: "png" 或 output_format: "webp" 搭配。JPEG 不支持 Alpha 通道。

moderation string

内容审核强度。可选值:auto、low。

未传时,OpenVeer 会显式使用 low;传入 auto 时则按 auto 执行。

image_urls string[]

图生图或图像编辑使用的参考图 URL 数组,最多 16 张。传入后自动进入编辑模式。

仅接受公网可访问的 HTTP(S) URL。本地图片请先调用 POST /v1/uploads/images 上传,再使用返回的 url。

尺寸规则

使用精确像素尺寸时,宽高必须同时满足以下条件:

  • 宽和高均为 16 的倍数
  • 任意单边不超过 3840 像素
  • 长边与短边之比不超过 3:1
  • 总像素在 655,360 \~ 8,294,400 之间
警告

高于 2560×1440 的分辨率属于实验性范围,稳定性可能低于常用分辨率。

比例与分辨率映射

size 1k 2k 4k
1:1 1024×1024 2048×2048 2880×2880
3:2 1536×1024 2048×1360 3520×2336
2:3 1024×1536 1360×2048 2336×3520
4:3 1024×768 2048×1536 3312×2480
3:4 768×1024 1536×2048 2480×3312
5:4 1280×1024 2560×2048 3216×2576
4:5 1024×1280 2048×2560 2576×3216
16:9 1536×864 2048×1152 3840×2160
9:16 864×1536 1152×2048 2160×3840
2:1 2048×1024 2688×1344 3840×1920
1:2 1024×2048 1344×2688 1920×3840
21:9 2016×864 2688×1152 3840×1648
9:21 864×2016 1152×2688 1648×3840
3:1 1536×512 3072×1024 3840×1280
1:3 512×1536 1024×3072 1280×3840

也可以直接传入满足尺寸规则的任意精确像素值,不限于上表中的组合。

使用示例

文生图

{
  "model": "gpt-image-2.5-flare",
  "prompt": "未来感城市中的空中花园,清晨薄雾,建筑摄影",
  "size": "16:9",
  "resolution": "2k",
  "quality": "high",
  "n": 1
}

使用 Sunburst 精细编辑

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "保留商品主体和包装文字,将背景替换为柔和的米白色摄影棚,并增加自然投影",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "resolution": "2k",
  "quality": "xhigh"
}

多参考图编辑

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "以第一张图的商品为主体,参考第二张图的布景和第三张图的光线,生成横版广告图",
  "image_urls": [
    "https://example.com/product.png",
    "https://example.com/set.jpg",
    "https://example.com/lighting.jpg"
  ],
  "size": "16:9",
  "resolution": "2k",
  "quality": "max"
}

透明背景

{
  "model": "gpt-image-2.5-flare",
  "prompt": "一双白色运动鞋的电商产品图,主体完整,透明背景",
  "size": "1:1",
  "resolution": "2k",
  "quality": "high",
  "background": "transparent",
  "output_format": "png"
}

精确像素尺寸

{
  "model": "gpt-image-2.5-flare",
  "prompt": "极简风格的产品发布会主视觉",
  "size": "1600x1200",
  "quality": "medium"
}

提交响应

提交成功后会立即返回异步任务 ID:

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
警告

data 是数组,请读取 data[0].task_id。

查询任务结果

使用提交响应中的 task_id 调用 任务查询接口:

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

建议每 2 \~ 5 秒轮询一次,直到状态变为 completed 或 failed。

任务成功

{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.0159,
    "credits_cost": 0.159,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.openveer.com/f/image/example.png"
          ],
          "expires_at": 1789000000
        }
      ]
    },
    "usage": {
      "input_tokens": 19,
      "output_tokens": 527,
      "total_tokens": 546
    }
  }
}

图片地址位于 data.result.images[].url[]。请及时下载并转存,不要将临时 URL 用作长期存储。

批量查询多个任务时,可使用 POST /v1/tasks/batch。

状态 含义
submitted 任务已提交
processing 正在生成
completed 生成成功,可读取 result.images
failed 生成失败,查看 error.message;预扣费用会自动退回

计费说明

GPT-Image-2.5 按实际 token 用量计费,Flare 与 Sunburst 单价相同。最终费用请以 价格页面 或 /api/pricing 返回的实时值为准。

官方 token 单价

项目 每 100 万 token 单价
图片输出 \$36.00
图片输入 \$9.60
图片输入(缓存命中) \$2.40
文本输入 \$6.00
文本输入(缓存命中) \$1.50

实际扣费还会受到账号分组倍率和折扣影响。

1024×1024 输出 token 参考

quality 输出 token 官方输出成本
low 235 \$0.00706
medium 527 \$0.01580
high 2107 \$0.06322
xhigh 3746 \$0.11239
max 8429 \$0.25286
警告

quality: "auto" 的实际档位由模型运行时决定。提交时会按当前尺寸的最高档 max 预留额度,任务完成后再按真实 token 用量结算并退回差额。余额敏感时建议显式指定 quality。

当 n > 1 时,预扣额度会按图片数量线性增加,最终按实际生成张数结算。任务失败会自动退款。

输出 token 参考表

下表为各比例、分辨率和质量组合的单张图片输出 token 参考值。实际账单还会包含提示词及参考图的输入 token。

尺寸 实际像素 low medium high xhigh max
1:1 1024×1024 235 527 2107 3746 8429
3:2 1536×1024 190 412 1646 2951 6586
2:3 1024×1536 190 412 1646 2951 6586
4:3 1024×768 161 361 1445 2568 5778
3:4 768×1024 161 361 1445 2568 5778
5:4 1280×1024 208 454 1812 3242 7343
4:5 1024×1280 208 454 1812 3242 7343
16:9 1536×864 144 336 1294 2300 5174
9:16 864×1536 144 336 1294 2300 5174
2:1 2048×1024 158 354 1416 2518 5664
1:2 1024×2048 158 354 1416 2518 5664
21:9 2016×864 126 270 1132 1940 4418
9:21 864×2016 126 270 1132 1940 4418
3:1 1536×512 67 161 642 1124 2568
1:3 512×1536 67 161 642 1124 2568
1:1@2k 2048×2048 476 1070 4282 7612 17126
3:2@2k 2048×1360 253 552 2206 3859 8821
2:3@2k 1360×2048 253 552 2206 3859 8821
4:3@2k 2048×1536 296 667 2668 4742 10670
3:4@2k 1536×2048 296 667 2668 4742 10670
5:4@2k 2560×2048 452 991 3964 7093 16062
4:5@2k 2048×2560 452 991 3964 7093 16062
16:9@2k 2048×1152 188 440 1696 3013 6780
9:16@2k 1152×2048 188 440 1696 3013 6780
2:1@2k 2688×1344 216 486 1940 3449 7759
1:2@2k 1344×2688 216 486 1940 3449 7759
21:9@2k 2688×1152 172 367 1542 2642 6019
9:21@2k 1152×2688 172 367 1542 2642 6019
3:1@2k 3072×1024 124 296 1186 2075 4742
1:3@2k 1024×3072 124 296 1186 2075 4742
1:1@4k 2880×2880 791 1780 7116 12650 28463
3:2@4k 3520×2336 540 1178 4711 8244 18844
2:3@4k 2336×3520 540 1178 4711 8244 18844
4:3@4k 3312×2480 589 1325 5296 9414 21180
3:4@4k 2480×3312 589 1325 5296 9414 21180
5:4@4k 3216×2576 642 1408 5628 10072 22807
4:5@4k 2576×3216 642 1408 5628 10072 22807
16:9@4k 3840×2160 445 1038 4003 7116 16010
9:16@4k 2160×3840 445 1038 4003 7116 16010
2:1@4k 3840×1920 360 810 3240 5759 12958
1:2@4k 1920×3840 360 810 3240 5759 12958
21:9@4k 3840×1648 281 600 2519 4318 9835
9:21@4k 1648×3840 281 600 2519 4318 9835
3:1@4k 3840×1280 167 398 1594 2789 6373
1:3@4k 1280×3840 167 398 1594 2789 6373
## 限制
项目 限制
单次生成数量 n 1 \~ 4
参考图数量 最多 16 张
单边像素 不超过 3840,且为 16 的倍数
总像素 655,360 \~ 8,294,400
长短边比例 不超过 3:1
输出格式 PNG / JPEG / WebP
透明背景 仅 PNG / WebP
流式部分图 暂不支持

常见错误

场景 原因与处理
quality 不受支持 xhigh / max 仅支持 GPT-Image-2.5;更换模型或调整档位
精确像素宽高不是 16 的倍数 调整到满足尺寸规则的像素值
background=transparent 搭配 jpeg 将 output_format 改为 png 或 webp
参考图超过 16 张 减少 image_urls 中的图片数量
账户余额不足 充值后重试;使用 auto 时需注意最高档预留额度

Response

code integer

响应状态码,提交成功时为 200。

data array
提交响应数据。
status string

初始状态为 submitted。

task_id string

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