GPT Image 2.5 图像生成 - apimax · AI 大模型 API 聚合平台

GPT Image 2.5（gpt-image-2.5-sunburst / gpt-image-2.5-flare）是 OpenAI 的新一代图像生成模型,支持文生图、图生图与图像编辑(局部重绘)。本接口完全兼容 OpenAI Images API 格式,并采用异步任务模式:提交后立即返回任务 ID,再通过查询接口轮询结果。

- 异步模式走独立端点 POST /v1/images/async-generations,提交后返回 task_id,使用查询任务接口获取结果。 - 生成的图像链接为预签名 URL,有效期约 24 小时,请及时保存。

鉴权#

所有接口均需通过 Bearer Token 认证。请在 API Key 管理页面创建你的 Key,并在请求头中添加:

text

Authorization: Bearer YOUR_API_KEY

创建任务#

POST /v1/images/async-generations

请求参数#

参数	类型	必填	默认	说明
`model`	string	是	`gpt-image-2.5-sunburst`	模型名称，可选 `gpt-image-2.5-sunburst` 或 `gpt-image-2.5-flare`
`prompt`	string	是	—	提示词,描述要生成或编辑的图像。最多 32000 字符
`image_urls`	array	否	—	参考图 URL 列表,用于图生图/图像编辑。1~16 张,单张 < 20MB
`size`	string	否	`auto`	图像尺寸,支持比例格式(如 `16:9`)或像素格式(如 `1024x1024`)
`resolution`	string	否	`1K`	分辨率档位 `1K`/`2K`/`4K`,仅在 `size` 为比例格式时生效
`quality`	string	否	`auto`	图像质量：`low`（低）、`medium`（中）、`high`（高）、`xhigh`（超高）和 `max`（最高）；2.5 系列支持全部档位
`background`	string	否	`auto`	背景模式：`auto`（自动）、`opaque`（不透明）、`transparent`（透明）
`callback_url`	string	否	—	任务完成后的 HTTPS 回调地址

quality 质量#

支持 low、medium、high、xhigh、max 和 auto。其中 medium 是均衡档位；GPT Image 2.5 的 xhigh 与 max 用于更高质量输出。

json

{
  "model": "gpt-image-2.5",
  "prompt": "一只可爱的猫咪",
  "quality": "medium"
}

size 尺寸#

支持两种写法,默认 auto(由模型自动决定,此时 resolution 不生效)。

① 比例格式(推荐,15 种):

1:1、1:2、2:1、1:3、3:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、9:21、21:9

② 显式像素格式: WxH(或 W×H),如 1024x1024、1536x1024、3840×2160

宽、高均须为 16 的整数倍,每条边范围 [16, 3840]
像素预算:655,360 ≤ width × height ≤ 8,294,400(约 0.65MP ~ 8.29MP)
长宽比 ≤ 3:1

比例 + resolution 组合若超出像素预算,会自动按比例缩到顶格(例如 4K + 2:1 → 3840×1920)。

resolution 分辨率档位#

仅在 size 为比例格式时生效,显式像素格式下被忽略。

档位	目标像素	`1:1`	`16:9`	`2:1`
`1K`	~1MP	1024×1024	1360×768	1456×720
`2K`	~4MP	2048×2048	2736×1536	2896×1456
`4K`	~8.29MP	2880×2880	3840×2160	3840×1920

取值大小写不敏感。

background 透明背景#

GPT Image 2.5 现在支持生成透明背景图。将 background 设置为 transparent 即可开启透明背景,输出为 png 或 webp 格式。background 默认值为 auto,也可以显式设置为 opaque 生成不透明背景。

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "一只简洁的白色猫咪图标，背景透明",
  "background": "transparent"
}

请求示例#

请求体与同步 OpenAI Images API 同构。最简文生图只需 model 与 prompt:

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "海面上绚丽多彩的美丽日落"
}

高清横版(比例 + 分辨率档位 + 质量):

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "黄昏时分未来都市天际线的电影级广角镜头",
  "size": "16:9",
  "resolution": "4K",
  "quality": "high"
}

图生图 / 图像编辑(传入参考图):

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "在她旁边加一只可爱的小猫",
  "size": "1:1",
  "resolution": "1K",
  "image_urls": ["https://example.com/input.png"],
  "callback_url": "https://your-domain.com/webhook/image-done"
}

创建任务响应#

提交成功后立即返回任务信息(HTTP 200):

json

{
  "id": "task_V1StGXR8_Z5jdHi6B",
  "object": "image.generation.task",
  "type": "image",
  "status": "queued",
  "progress": 0,
  "created": 1757156493,
  "model": "gpt-image-2.5-sunburst",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 100
  }
}

id 即任务标识(task_ 前缀),用于后续查询。

查询任务#

GET /v1/tasks/{id}

bash

curl 'https://api.apimax.ai/v1/tasks/task_V1StGXR8_Z5jdHi6B' \
  --header 'Authorization: Bearer <token>'

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

生成结果以 data 实际返回为准:个别图片可能生成失败,此时任务仍为 completed,仅返回成功的图片,并按实际成功张数计费。

已完成(`completed`):

json

{
  "id": "task_V1StGXR8_Z5jdHi6B",
  "object": "image.generation.task",
  "type": "image",
  "status": "completed",
  "progress": 100,
  "created": 1757156493,
  "completed_at": 1757156593,
  "model": "gpt-image-2.5-sunburst",
  "data": [
    {
      "url": "https://cdn.example.com/img/.../0.png?X-Amz-Signature=...",
      "url_expires_at": 1757160193
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4160,
    "total_tokens": 4172
  }
}

预签名 URL 每次查询都会重新签发,因此轮询即可"刷新"过期链接。

失败(`failed`):

json

{
  "id": "task_V1StGXR8_Z5jdHi6B",
  "object": "image.generation.task",
  "type": "image",
  "status": "failed",
  "failed_at": 1757156593,
  "model": "gpt-image-2.5-sunburst",
  "error": {
    "code": "upstream_error",
    "message": "openai returned 400: content_policy_violation"
  }
}

status 状态#

状态	含义
`queued`	已入队,等待执行
`in_progress`	正在生成
`completed`	生成完成,`data` 中为图像链接
`failed`	生成失败,见 `error`

error.code 错误码#

Code	含义
`upstream_error`	上游返回 4xx(内容策略 / 提示词非法)
`upstream_unavailable`	上游多次重试后仍 5xx
`storage_error`	结果上传云存储失败
`internal_error`	网关内部异常

任务失败会自动退还预扣的配额。

错误码(HTTP)#

状态码	code	含义
400	`invalid_request`	缺少 prompt/model,或参数格式不正确
400	`model_not_supported`	模型不是 gpt-image-* 系列
401	`unauthorized`	Token 无效或过期
402	`insufficient_quota`	配额不足,请充值
403	`model_access_denied`	Token 无该模型访问权限
429	`rate_limit_exceeded`	请求过于频繁
500	`internal_error`	服务器内部错误

回调(callback_url)#

设置 callback_url 后,任务完成 / 失败 / 取消时网关会主动 POST 回调,回调体格式与查询任务接口一致。

仅支持 HTTPS,禁止回调到内网 IP,URL ≤ 2048 字符
超时 10 秒,失败最多重试 3 次(分别在 1s / 2s / 4s 后)
回调返回 2xx 视为成功,其他状态码触发重试

GPT Image 2.5 系列模型#

GPT Image 2.5 提供两个可用模型：

gpt-image-2.5-sunburst：适合通用文生图、图生图与图像编辑。
gpt-image-2.5-flare：适合需要更强光影表现与视觉风格控制的创作。

除模型名外，两者使用相同的请求参数、异步任务流程和返回结构。将请求中的 model 替换为对应模型即可。

鉴权#

创建任务#

请求参数#

quality 质量#

size 尺寸#

resolution 分辨率档位#

background 透明背景#

请求示例#

创建任务响应#

查询任务#

status 状态#

error.code 错误码#

错误码(HTTP)#

回调(callback_url)#

GPT Image 2.5 系列模型#

下一步