GPT Image 2 Pro 图片生成 API 文档

概述

GPT Image 2 Pro 图片生成接口，支持文生图（text-to-image）和图生图（image-to-image）两种模式。

Pro 为高可靠版本：同一请求会多路并发生成、先返回者胜出，以更低的失败率与更短的等待获得结果；请求参数、响应结构、查询与回调方式均与标准版完全一致，仅生成链路与计费不同（Pro 单价为标准版的 2 倍）。

Base URL: https://api.apiverse.ai

认证方式

所有接口均需要在请求头中携带 Token 进行认证：

Authorization: Bearer {YOUR_AUTH_TOKEN}

快速开始

cURL 示例

创建 GPT Image 2 Pro 任务（文生图）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gpt-image-2-pro" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over the ocean, oil painting style",
    "aspectRatio": "16:9"
  }'

创建 GPT Image 2 Pro 任务（图生图）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gpt-image-2-pro" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transform the image into watercolor style",
    "genType": "i2i",
    "imageUrls": ["https://example.com/reference.jpg"]
  }'

查询任务状态

curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_abc123" \
  -H "Authorization: Bearer your_auth_token_here"

接口列表

1. 创建 GPT Image 2 Pro 任务

POST /api/v2/open/aigc/gpt-image-2-pro

创建一个 GPT Image 2 Pro 图片生成任务。

Content-Type: application/json

请求参数

参数	类型	必填	说明
prompt	string	是	图片描述提示词，最多 20,000 字符
genType	string	否	生成类型：`t2i`(文生图,默认) / `i2i`(图生图)
imageUrls	string[]	条件	输入图片 URL 列表，图生图时必填，最多 16 张
base64File	string	否	Base64 编码的图片数据，支持 jpg/png/gif/webp，最大 10MB
base64FileList	string[]	否	Base64 编码的多张图片数据，每张支持 jpg/png/gif/webp，单张最大 10MB
aspectRatio	string	否	宽高比，默认 `auto`，支持：`auto` / `1:1` / `16:9` / `9:16` / `5:4` / `4:5` / `3:2` / `2:3` / `4:3` / `3:4` / `21:9`
resolution	string	否	输出分辨率：`1K` / `2K` / `4K`。注：1:1比例无法生成4K；auto比例或未传递比例参数时只能生成1K
callbackUrl	string	否	任务完成后的回调通知 URL

说明：
- base64File、imageUrls、base64FileList 可同时使用，图片处理顺序为：base64File（单张，放最前面）→ imageUrls（URL列表）→ base64FileList（多张base64，追加到末尾）
- 图生图时必须提供输入图片

请求示例

文生图：

{
  "prompt": "A beautiful sunset over the ocean, oil painting style",
  "aspectRatio": "16:9"
}

图生图：

{
  "prompt": "Transform this image into watercolor style",
  "genType": "i2i",
  "imageUrls": ["https://example.com/reference.jpg"]
}

图生图（多图输入）：

{
  "prompt": "Combine the elements from these images into a new artwork",
  "genType": "i2i",
  "imageUrls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "aspectRatio": "1:1"
}

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID，用于查询任务状态
data.status	string	任务状态，创建时固定为 `processing`
data.createdAt	string	创建时间

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260423103000_abc12345",
    "status": "processing",
    "createdAt": "2026-04-23 10:30:00"
  }
}

1.5 图片编辑（genType=edit）

图片编辑复用创建任务接口 POST /api/v2/open/aigc/gpt-image-2-pro，通过 genType 设为 edit 触发：

POST /api/v2/open/aigc/gpt-image-2-pro

图片编辑是图生图的特例：必须提供一张主图（被编辑的原图，取输入图片的第一张），
并额外支持 maskUrl/maskFile（蒙版）与 n（生成数量）。返回 taskId 后，使用
「查询任务状态」接口轮询，或通过 callbackUrl 接收回调。

Content-Type: application/json

请求参数

参数	类型	必填	说明
genType	string	是	固定传 `edit` 触发图片编辑
prompt	string	是	编辑指令提示词，最多 20,000 字符
imageUrls	string[]	条件	输入图片 URL 列表，第一张为主图，最多 16 张。与 `base64File`/`base64FileList` 至少提供其一
base64File	string	否	Base64 编码的主图，支持 jpg/png/gif/webp，最大 10MB（放在最前，作为主图）
base64FileList	string[]	否	Base64 编码的多张图片数据，单张最大 10MB
maskUrl	string	否	蒙版图 URL。蒙版中透明区域表示需要编辑的部位
maskFile	string	否	Base64 编码的蒙版图，最大 10MB
n	int	否	生成数量，范围 1-10，默认 1。按生成数量计费
aspectRatio	string	否	宽高比，默认 `auto`，取值同「创建任务」接口
resolution	string	否	输出分辨率：`1K` / `2K` / `4K`，默认 `1K`
callbackUrl	string	否	任务完成后的回调通知 URL

说明：genType=edit 时必须提供主图，否则返回参数错误。图片处理顺序与创建任务一致：
base64File（主图，最前）→ imageUrls → base64FileList。

请求示例

{
  "genType": "edit",
  "prompt": "给猫戴上一顶生日帽",
  "imageUrls": ["https://example.com/cat.jpg"],
  "maskUrl": "https://example.com/mask.png",
  "n": 2
}

响应参数

响应结构与「创建任务」接口一致（返回 taskId / status / createdAt）。

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260423103000_edit5678",
    "status": "processing",
    "createdAt": "2026-04-23 10:30:00"
  }
}

2. 查询任务状态

GET /api/v2/open/aigc/{taskId}

查询单个任务的执行状态。

路径参数

参数	类型	必填	说明
taskId	string	是	任务 ID

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID
data.status	string	任务状态：`processing` / `success` / `failed`
data.result	string[]	生成的图片 URL 列表（成功时返回）
data.errorCode	string	错误码（失败时返回）
data.errorMsg	string	错误信息（失败时返回）
data.taskNickname	string	任务昵称（创建时传入则返回）
data.progress	int	进度，0-100
data.pointConsume	string	实际消费点数（decimal 字符串）
data.createdAt	string	创建时间（字符串）
data.updatedAt	string	更新时间（字符串）
data.createTime	int	创建时间（Unix 秒）
data.updateTime	int	更新时间（Unix 秒）
data.completeTime	int	完成时间（Unix 秒，完成时返回）
data.costTime	int	耗时（秒，完成时返回）

响应示例

处理中

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260423103000_abc12345",
    "status": "processing",
    "createdAt": "2026-04-23 10:30:00",
    "updatedAt": "2026-04-23 10:30:05"
  }
}

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260423103000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/04/23/output_001.png"
    ],
    "createdAt": "2026-04-23 10:30:00",
    "updatedAt": "2026-04-23 10:31:30"
  }
}

失败

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260423103000_abc12345",
    "status": "failed",
    "errorMsg": "生成失败：内容不符合规范",
    "createdAt": "2026-04-23 10:30:00",
    "updatedAt": "2026-04-23 10:30:45"
  }
}

3. 批量查询任务状态

POST /api/v2/open/aigc/batch

批量查询多个任务的执行状态（最多 100 个）。

请求参数

参数	类型	必填	说明
taskIds	string[]	是	任务 ID 列表，最多 100 个

请求示例

{
  "taskIds": ["task_20260423103000_abc12345", "task_20260423103200_def67890"]
}

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "tasks": [
      {
        "taskId": "task_20260423103000_abc12345",
        "status": "success",
        "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/output_001.png"],
        "createdAt": "2026-04-23 10:30:00",
        "updatedAt": "2026-04-23 10:31:30"
      },
      {
        "taskId": "task_20260423103200_def67890",
        "status": "processing",
        "createdAt": "2026-04-23 10:32:00",
        "updatedAt": "2026-04-23 10:32:05"
      }
    ]
  }
}

回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 callbackUrl，系统会向该 URL 发送 POST 请求。

回调请求

Headers

Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}

Body

回调请求体为统一外层结构，任务详情包裹在 data 字段中（结构与「查询任务状态」接口的 data 完全一致）：

{
  "event": "task.completed",
  "timestamp": "2026-04-23T10:31:30+08:00",
  "signature": "a1b2c3d4e5f6...",
  "data": {
    "taskId": "task_20260423103000_abc12345",
    "status": "success",
    "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/output_001.png"],
    "createdAt": "2026-04-23 10:30:00",
    "updatedAt": "2026-04-23 10:31:30"
  }
}

字段	类型	说明
event	string	事件类型，固定 `task.completed`
timestamp	string	事件时间（RFC3339）
signature	string	签名，HMAC-SHA256(`taskId` + `timestamp`)，同时通过 `X-Funcloud-Signature` 头传递，可用于校验回调来源
data	object	任务详情，结构与「查询任务状态」接口返回的 `data` 完全一致

回调响应

接收方应返回 HTTP 2xx 状态码表示成功接收：

{
  "code": 0,
  "msg": "ok"
}

错误码

code	说明
0	成功
10002	参数缺失或格式错误
10005	API Key 无效或缺失
30003	异步任务不存在，请检查 task_id
90003	服务器内部错误

最佳实践

1. 轮询策略

建议的轮询间隔：
- 前 30 秒：每 3 秒查询一次
- 30 秒 ~ 2 分钟：每 5 秒查询一次
- 2 分钟后：每 10 秒查询一次

2. 使用回调

对于生产环境，建议使用回调通知而非轮询，可以：
- 减少 API 调用次数
- 更快获得结果通知
- 降低服务器压力

3. 处理时间参考

文生图：通常 10 ~ 60 秒
图生图：通常 10 ~ 60 秒

4. Prompt 编写建议

使用清晰、具体的描述
可以指定艺术风格（如 oil painting, watercolor, digital art 等）
图生图时，prompt 应描述希望对原图进行的变换
支持多语言，但英文效果通常更好