GPT-Image-2.5 图像生成

curl --request POST \
  --url https://api.apimart.ai/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
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1,
    },
)

print(response.json())

const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      prompt: "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
      size: "1:1",
      resolution: "1k",
      quality: "medium",
      n: 1,
    }),
  },
);

console.log(await response.json());

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

{
  "error": {
    "code": 400,
    "message": "请求参数无效",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的 API 密钥",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "账户余额不足，请充值后再试",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": 500,
    "message": "服务器内部错误，请稍后重试",
    "type": "server_error"
  }
}

POST

images

generations

curl --request POST \
  --url https://api.apimart.ai/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
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1,
    },
)

print(response.json())

const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      prompt: "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
      size: "1:1",
      resolution: "1k",
      quality: "medium",
      n: 1,
    }),
  },
);

console.log(await response.json());

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

{
  "error": {
    "code": 400,
    "message": "请求参数无效",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的 API 密钥",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "账户余额不足，请充值后再试",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": 500,
    "message": "服务器内部错误，请稍后重试",
    "type": "server_error"
  }
}

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

curl --request POST \
  --url https://api.apimart.ai/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
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1,
    },
)

print(response.json())

const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      prompt: "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
      size: "1:1",
      resolution: "1k",
      quality: "medium",
      n: 1,
    }),
  },
);

console.log(await response.json());

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

{
  "error": {
    "code": 400,
    "message": "请求参数无效",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的 API 密钥",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "账户余额不足，请充值后再试",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": 500,
    "message": "服务器内部错误，请稍后重试",
    "type": "server_error"
  }
}

认证

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 消耗约为上一代同名档位的四分之一。

请求参数

string

必填

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

gpt-image-2.5-flare
gpt-image-2.5-sunburst

string

必填

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

string

默认值:"auto"

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

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 自动计算输出尺寸。

string

默认值:"1k"

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

1k（默认）
2k
4k

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

string

默认值:"auto"

图片质量档位。

low
medium
high
xhigh
max
auto（默认，由模型运行时决定）

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

integer

默认值:"1"

生成图片数量，取值范围为 1 ~ 4。必须传入数字，不要使用字符串。

string

默认值:"png"

输出文件格式。

png（默认，支持透明背景）
jpeg
webp（支持透明背景）

integer

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

string

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

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

string

默认值:"low"

内容审核强度。可选值：auto、low。未传时，APIMart 会显式使用 low；传入 auto 时则按 auto 执行。

string[]

图生图或图像编辑使用的参考图 URL 数组，最多 16 张。传入后自动进入编辑模式。仅接受公网可访问的 HTTP(S) URL。本地图片请先调用 POST /v1/uploads/images 上传，再使用返回的 url。

string

局部重绘使用的蒙版图，仅在同时传入 image_urls 时生效。gpt-image-2.5-flare 和 gpt-image-2.5-sunburst 均支持此参数。参数为单个字符串，支持以下格式：

可由服务器直接下载的 HTTP(S) 图片直链
data:image/png;base64,... 格式的 PNG Data URL

蒙版要求：

使用带 Alpha 透明通道的 PNG，建议输入原图也使用 PNG
像素宽高必须与 image_urls[0] 完全一致；匹配的是第一张输入原图，不是输出 size
Alpha 完全透明（alpha=0）的区域表示需要修改，其余区域用于保留
一次只能传入一张蒙版；使用多张参考图时，蒙版仅作用于第一张输入图
文件大小指南写的是小于 50 MB，而 mask 参数说明写的是小于 4 MB；未实测前建议按更严格的 4 MB 准备

普通黑白图片如果没有 Alpha 透明通道，不能直接作为蒙版。APIMart 不会自动补充透明通道，当前也不会预先校验蒙版与原图尺寸是否一致，这两点需由调用方保证。

HTTP(S) URL 必须无需 Cookie 或额外鉴权头即可访问；签名链接的有效期应覆盖任务排队和执行时间。默认下载限制为 20 MB，超时时间为 60 秒，具体部署可能覆盖这两个默认值。蒙版用于引导模型编辑，模型不保证蒙版边界外的像素完全不变。

尺寸规则

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

宽和高均为 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"
}

使用蒙版局部重绘

以下示例只修改蒙版中 Alpha 完全透明的区域。蒙版尺寸必须与 product.png 一致：

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "仅将透明蒙版覆盖的区域替换为金色丝带，保留商品主体和其他背景",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "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.apimart.ai/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'

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

任务成功

{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "credits_cost": 0.1325,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example.png"
          ],
          "expires_at": 1789000000
        }
      ]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}

图片地址位于 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 单价
图片输出	$30.00
图片输入	$8.00
图片输入（缓存命中）	$2.00
文本输入	$5.00
文本输入（缓存命中）	$1.25

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

1024×1024 输出 token 参考

`quality`	输出 token	官方输出成本
`low`	196	$0.00588
`medium`	439	$0.01317
`high`	1756	$0.05268
`xhigh`	3122	$0.09366
`max`	7024	$0.21072

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

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

输出 token 参考表

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

尺寸	实际像素	low	medium	high	xhigh	max
`1:1`	1024×1024	196	439	1756	3122	7024
`3:2`	1536×1024	158	343	1372	2459	5488
`2:3`	1024×1536	158	343	1372	2459	5488
`4:3`	1024×768	134	301	1204	2140	4815
`3:4`	768×1024	134	301	1204	2140	4815
`5:4`	1280×1024	173	378	1510	2702	6119
`4:5`	1024×1280	173	378	1510	2702	6119
`16:9`	1536×864	120	280	1078	1917	4312
`9:16`	864×1536	120	280	1078	1917	4312
`2:1`	2048×1024	132	295	1180	2098	4720
`1:2`	1024×2048	132	295	1180	2098	4720
`21:9`	2016×864	105	225	943	1617	3682
`9:21`	864×2016	105	225	943	1617	3682
`3:1`	1536×512	56	134	535	937	2140
`1:3`	512×1536	56	134	535	937	2140
`1:1@2k`	2048×2048	397	892	3568	6343	14272
`3:2@2k`	2048×1360	211	460	1838	3216	7351
`2:3@2k`	1360×2048	211	460	1838	3216	7351
`4:3@2k`	2048×1536	247	556	2223	3952	8892
`3:4@2k`	1536×2048	247	556	2223	3952	8892
`5:4@2k`	2560×2048	377	826	3303	5911	13385
`4:5@2k`	2048×2560	377	826	3303	5911	13385
`16:9@2k`	2048×1152	157	367	1413	2511	5650
`9:16@2k`	1152×2048	157	367	1413	2511	5650
`2:1@2k`	2688×1344	180	405	1617	2874	6466
`1:2@2k`	1344×2688	180	405	1617	2874	6466
`21:9@2k`	2688×1152	143	306	1285	2202	5016
`9:21@2k`	1152×2688	143	306	1285	2202	5016
`3:1@2k`	3072×1024	103	247	988	1729	3952
`1:3@2k`	1024×3072	103	247	988	1729	3952
`1:1@4k`	2880×2880	659	1483	5930	10542	23719
`3:2@4k`	3520×2336	450	982	3926	6870	15703
`2:3@4k`	2336×3520	450	982	3926	6870	15703
`4:3@4k`	3312×2480	491	1104	4413	7845	17650
`3:4@4k`	2480×3312	491	1104	4413	7845	17650
`5:4@4k`	3216×2576	535	1173	4690	8393	19006
`4:5@4k`	2576×3216	535	1173	4690	8393	19006
`16:9@4k`	3840×2160	371	865	3336	5930	13342
`9:16@4k`	2160×3840	371	865	3336	5930	13342
`2:1@4k`	3840×1920	300	675	2700	4799	10798
`1:2@4k`	1920×3840	300	675	2700	4799	10798
`21:9@4k`	3840×1648	234	500	2099	3598	8196
`9:21@4k`	1648×3840	234	500	2099	3598	8196
`3:1@4k`	3840×1280	139	332	1328	2324	5311
`1:3@4k`	1280×3840	139	332	1328	2324	5311

限制

项目	限制
单次生成数量 `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

integer

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

array

提交响应数据。

显示数组元素

string

初始状态为 submitted。

string

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

概览

模型

文字系列

图像系列

视频系列

音频系列

审核系列

上传管理

任务管理

账户管理

GPT-Image-2.5 图像生成

认证

模型选择

请求参数

尺寸规则

比例与分辨率映射

使用示例

文生图

使用 Sunburst 精细编辑

使用蒙版局部重绘

多参考图编辑

透明背景

精确像素尺寸

提交响应

查询任务结果

任务成功

计费说明

官方 token 单价

1024×1024 输出 token 参考

输出 token 参考表

限制

常见错误

Response

​认证

​模型选择

​请求参数

​尺寸规则

​比例与分辨率映射

​使用示例

​文生图

​使用 Sunburst 精细编辑

​使用蒙版局部重绘

​多参考图编辑

​透明背景

​精确像素尺寸

​提交响应

​查询任务结果

​任务成功

​计费说明

​官方 token 单价

​1024×1024 输出 token 参考

​输出 token 参考表

​限制

​常见错误

​Response

认证

模型选择

请求参数

尺寸规则

比例与分辨率映射

使用示例

文生图

使用 Sunburst 精细编辑

使用蒙版局部重绘

多参考图编辑

透明背景

精确像素尺寸

提交响应

查询任务结果

任务成功

计费说明

官方 token 单价

1024×1024 输出 token 参考

输出 token 参考表

限制

常见错误

Response