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

GPT Image Web(gpt-image-web)是 Web 渠道的图像生成模型，支持基础文生图与图生图。本接口采用异步任务模式：提交后立即返回任务 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-web`	模型名称,固定为 `gpt-image-web`
`prompt`	string	是	—	提示词,描述要生成或编辑的图像。最多 32000 字符
`image_urls`	array	否	—	参考图 URL 列表,用于图生图/图像编辑。1~16 张,单张 < 20MB
`size`	string	否	`auto`	图像尺寸,支持比例格式(如 `16:9`)或像素格式(如 `1024x1024`);输出最高 2K,更大尺寸会被缩小到 2K
`callback_url`	string	否	—	任务完成后的 HTTPS 回调地址

size 尺寸#

默认值为 auto。可传入比例或显式像素尺寸。

比例格式:

比例	说明
`1:1`	正方形
`2:3` / `3:2`	照片比例(竖 / 横)
`3:4` / `4:3`	经典显示比例(竖 / 横)
`4:5` / `5:4`	社交图文比例(竖 / 横)
`9:16` / `16:9`	视频画面比例(竖 / 横)
`9:21` / `21:9`	超宽比例(竖 / 横)
`1:2` / `2:1`	长条比例(竖 / 横)
`1:3` / `3:1`	极长条比例(竖 / 横)

像素格式:宽x高,如 1024x1024、1536x1024、1920x1080。宽高需为 16 的倍数,单边范围 16–3840,长宽比不超过 3:1。

分辨率上限:生成图片最高输出 2K 分辨率。传入更大的尺寸(如 3840x2160)不会报错,会被自动缩小到 2K 以内输出。

请求示例#

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

json

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

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

json

{
  "model": "gpt-image-web",
  "prompt": "在她旁边加一只可爱的小猫",
  "size": "1:1",
  "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-web",
  "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-web",
  "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-web",
  "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 视为成功,其他状态码触发重试

鉴权#

创建任务#

请求参数#

size 尺寸#

请求示例#

创建任务响应#

查询任务#

status 状态#

error.code 错误码#

错误码(HTTP)#

回调(callback_url)#

下一步