GPT Image 2 图片生成 API（v1 / OpenAI 兼容协议）对接文档 API 文档

概述

本文档描述 OpenAI 路径兼容的 GPT Image 2 图片接口，包含两个端点：

端点	协议	说明
`POST /v1/images/generations`	异步（默认）/ 同步	文生图 / 图生图
`POST /v1/images/edits`	异步（默认）/ 同步	图片编辑（上传文件）

两个端点的请求体沿用 OpenAI images/generations、images/edits 的字段名，便于从其它平台迁移。

协议形态由 async 参数决定，默认异步：

异步（默认，async 不传或传 true）：创建任务后立即返回平台统一任务体
（{code,msg,data:{taskId,...}}），拿到 data.taskId 后轮询 GET /v1/images/generations/{taskId}。
此形态不能直接用 OpenAI SDK 的 images.generate() / images.edit() 解析返回值。
同步（async=false）：服务端阻塞等待出图，直接返回 OpenAI 标准图片响应
（{created,data:[{url}]}），可直接用 OpenAI SDK 解析。适合迁移已有的 OpenAI 调用代码。

生成大图（4K）时耗时较长，同步模式请把客户端超时放宽到 10 分钟以上；
批量生产场景建议用默认的异步模式，避免长时间占用连接。

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

认证方式

在请求头中携带 API Key 进行认证（与 v2 接口共用同一套密钥）：

Authorization: Bearer {YOUR_API_KEY}

快速开始

cURL 示例

文生图

curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A beautiful sunset over the ocean, oil painting style",
    "size": "1792x1024"
  }'

图生图

curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Transform this image into watercolor style",
    "image": ["https://example.com/reference.jpg"],
    "size": "1024x1024"
  }'

查询任务结果

curl "https://api.apiverse.ai/v1/images/generations/task_20260509150000_abc12345" \
  -H "Authorization: Bearer your_api_key_here"

接口说明

创建图片生成任务

POST /v1/images/generations

Content-Type: application/json

协议说明：默认异步——建单后立即返回 taskId（通常 1 秒内），不阻塞等待出图，
请用 GET /v1/images/generations/{taskId} 轮询，或用 callback_url 接收完成回调。
需要一次请求拿到图片时传 async=false，见下文「同步模式」。

请求参数

参数	类型	必填	说明
model	string	是	模型 ID，取值：`gpt-image-2`、`gpt-image-2-official`、`gpt-image-2-pro`
prompt	string	是	图片描述提示词，最多 20,000 字符（`gpt-image-2-official` 为 32,000）
image	string[]	否	输入图片列表（URL 或 Base64 data URI）。传入该字段即自动按图生图处理
mask	string	否	蒙版图（URL 或 Base64 data URI），需与 `image` 一起使用，用于局部重绘
size	string	否	画面比例或尺寸：可传 `16:9` 这类比例串，也可传 `1024x1024`、`1792x1024` 这类像素串（服务端按宽高比就近匹配标准比例），还可直接传 `1K`/`2K`/`4K` 指定清晰度
resolution	string	否	分辨率档 `1k` / `2k` / `4k`，优先级高于 `size` 里的档位与 `quality`
n	int	否	生成数量，默认 1，取值 1–10（`gpt-image-2-official` 为 1–4）
quality	string	否	质量档；`high` 在未传 `resolution` 且 `size` 不是档位串时升到 2K。`gpt-image-2-official` 取值 `auto`（默认）/`low`/`medium`/`high`
background	string	否	仅 `gpt-image-2-official`：背景处理，取值 `auto`（默认）/`opaque`/`transparent`。`transparent` 需搭配 `output_format=png`
moderation	string	否	仅 `gpt-image-2-official`：内容审核强度，取值 `auto`（默认）/`low`。与 `nsfw_check=true` 同传时强制为 `auto`
output_format	string	否	仅 `gpt-image-2-official`：输出图片格式，取值 `png`（默认）/`jpeg`
output_compression	int	否	仅 `gpt-image-2-official`：输出压缩率 0–100，仅在 `output_format=jpeg` 时生效
nsfw_check	boolean	否	安全审核开关；与 `extra_body.nsfw_checker` 同传时以本字段为准
async	boolean	否	协议形态，默认 `true`（异步返回 `taskId`）；传 `false` 阻塞至出图并返回 OpenAI 标准图片响应
response_format	string	否	仅 `async=false` 时生效：`url`（默认）或 `b64_json`
extra_body	object	否	模型私有参数，如 `{"nsfw_checker": true}`
callback_url	string	否	任务完成后的回调通知 URL
task_nickname	string	否	任务昵称，便于业务侧标记
user	string	否	调用方用户标识（OpenAI 兼容字段）

关于 size 的换算：服务端会把 WxH 尺寸换算成最接近的标准宽高比，候选比例为
1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9。例如 1792x1024 → 16:9，1024x1024 → 1:1。
未传 size 时使用模型默认比例。

gpt-image-2-official 走独立的比例表，支持
1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 2:1 / 1:2 / 3:1 / 1:3 / 21:9 / 9:21，
也可直接传该比例表内的像素串（如 1536x864、3840x2160），未命中时报 size 不支持。

关于输出分辨率：分辨率档优先级为 resolution > size 里的档位串 > quality。
例如 {"size":"16:9","resolution":"4k"} 得到 16:9 的 4K 图；只传 {"size":"2K"} 得到默认比例的 2K 图；
都不传时默认 1K。不同分辨率档计价不同。

关于 gpt-image-2-official：该模型按 token 计费（提示词 token + 参考图 token + 出图 token），
建单时按预估用量冻结额度，任务完成后按实际用量结算，查询结果返回完整 usage（见「查询图片任务」）；参考图最多 16 张，
mask 必须与 image 一起传。

请求示例

文生图：

{
  "model": "gpt-image-2",
  "prompt": "A beautiful sunset over the ocean, oil painting style",
  "size": "1792x1024"
}

图生图：

{
  "model": "gpt-image-2",
  "prompt": "Transform this image into watercolor style",
  "image": ["https://example.com/reference.jpg"],
  "size": "1024x1024"
}

指定比例 + 分辨率档：

{
  "model": "gpt-image-2",
  "prompt": "A surreal painting of a giant banana floating in space",
  "size": "16:9",
  "resolution": "4k"
}

gpt-image-2-official（透明背景 + PNG 输出）：

{
  "model": "gpt-image-2-official",
  "prompt": "A minimal logo of a paper crane, centered, clean edges",
  "size": "1:1",
  "resolution": "2k",
  "quality": "high",
  "background": "transparent",
  "output_format": "png"
}

gpt-image-2-official（JPEG 输出 + 压缩）：

{
  "model": "gpt-image-2-official",
  "prompt": "Product photo of a ceramic mug on a wooden table",
  "size": "3:2",
  "output_format": "jpeg",
  "output_compression": 80,
  "moderation": "low"
}

响应参数（建单成功）

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

响应示例（建单成功）

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-09 15:00:00"
  }
}

图片编辑

POST /v1/images/edits

Content-Type: multipart/form-data

在给定一张或多张原图与提示词的情况下，对图片进行编辑 / 重绘 / 扩展。接口路径与请求字段对齐 OpenAI
images/edits 协议，原图以文件形式上传（无需先转 URL 或 Base64）。

协议说明：默认异步——建单后立即返回 taskId，不阻塞等待出图，
请用 GET /v1/images/generations/{taskId} 轮询查询结果，与生成接口共用同一个查询端点。
传 async=false 可改为同步返回图片，见下文「同步模式」。

cURL 示例

curl -X POST "https://api.apiverse.ai/v1/images/edits" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "model=gpt-image-2" \
  -F "prompt=给猫戴上一顶生日帽" \
  -F "size=1024x1024" \
  -F "image=@/path/to/cat.png"

多张参考图 + 蒙版：

curl -X POST "https://api.apiverse.ai/v1/images/edits" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "model=gpt-image-2" \
  -F "prompt=把这两张图合成到同一个场景" \
  -F "n=2" \
  -F "image=@/path/to/img1.png" \
  -F "image=@/path/to/img2.png" \
  -F "mask=@/path/to/mask.png"

gpt-image-2-official + 扩展参数：

curl -X POST "https://api.apiverse.ai/v1/images/edits" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "model=gpt-image-2-official" \
  -F "prompt=把背景抠掉，只保留主体" \
  -F "size=1:1" \
  -F "resolution=2k" \
  -F "background=transparent" \
  -F "output_format=png" \
  -F "image=@/path/to/product.png"

请求参数（multipart/form-data）

本端点与 /v1/images/generations 走同一条链路，字段名与含义完全一致，
差别只在于原图/蒙版以文件上传，而不是 URL / Base64。因此上面表格里的参数在这里同样可用
（包括 gpt-image-2-official 的 background / moderation / output_format / output_compression）。

参数	类型	必填	说明
model	string	是	模型 ID，取值：`gpt-image-2`、`gpt-image-2-official`、`gpt-image-2-pro`
prompt	string	是	编辑指令提示词
image	file	是	待编辑的原图（二进制）。多张时重复传 `image` 字段即可
mask	file	否	蒙版图（二进制）。蒙版中透明区域表示需要编辑的部位
n	int	否	生成数量，默认 1。按生成数量计费
size	string	否	画面比例或尺寸，如 `16:9`、`1024x1024`，取值同生成接口
resolution	string	否	分辨率档 `1k` / `2k` / `4k`
quality	string	否	质量档，取值同生成接口
background	string	否	仅 `gpt-image-2-official`：`auto` / `opaque` / `transparent`
moderation	string	否	仅 `gpt-image-2-official`：`auto` / `low`
output_format	string	否	仅 `gpt-image-2-official`：`png` / `jpeg`
output_compression	int	否	仅 `gpt-image-2-official`：0–100，仅 `jpeg` 生效
nsfw_check	boolean	否	安全审核开关，传 `true` / `false`
async	boolean	否	协议形态，默认 `true`（异步返回 `taskId`）；传 `false` 阻塞至出图并返回 OpenAI 标准图片响应
response_format	string	否	仅 `async=false` 时生效：`url`（默认）或 `b64_json`
extra_body	string	否	模型私有参数，传 JSON 字符串，如 `{"nsfw_checker":true}`
image_urls	string	否	以 URL 形式追加参考图（可重复传），与上传文件可混用
mask_url	string	否	以 URL 形式提供蒙版图，未上传 `mask` 文件时生效
callback_url	string	否	任务完成后的回调通知 URL
task_nickname	string	否	任务昵称，便于业务侧标记
user	string	否	调用方用户标识（OpenAI 兼容字段）

各模型对 n、参考图张数、size 取值的限制与生成接口一致（如 gpt-image-2-official 的
n 为 1–4、参考图最多 16 张），超限时在建单响应里返回 code=10002 与具体原因。

响应参数（建单成功）

与 /v1/images/generations 完全一致：

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

响应示例（建单成功）

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-09 15:00:00"
  }
}

查询图片任务

GET /v1/images/generations/{taskId}

/v1/images/generations 与 /v1/images/edits 创建的任务都用本端点查询。
任务处于 processing 时请按「最佳实践」中的策略轮询，直到 success 或 failed。

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "success",
    "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/09/output_001.png"],
    "progress": 100,
    "createdAt": "2026-05-09 15:00:00",
    "updatedAt": "2026-05-09 15:00:25"
  }
}

同一任务也可用 GET /api/v2/open/aigc/{taskId} 查询，返回结构一致。

`gpt-image-2-official` 的 token 用量

model=gpt-image-2-official 的任务成功后，查询响应在上面字段之外额外返回：

字段	类型	说明
data.output	object	清洗后的官方完整响应。官方 `b64_json` 会落盘并替换成对应 URL，其余字段及完整 `usage` 原样保留
data.completionTokens	int	本次结算的实际总 token 数，等于 `output.usage.total_tokens`

其它模型不返回这两个字段。

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "success",
    "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/09/output_001.png"],
    "progress": 100,
    "createdAt": "2026-05-09 15:00:00",
    "updatedAt": "2026-05-09 15:00:25",
    "output": {
      "created": 1787661600,
      "data": [{ "url": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/09/output_001.png" }],
      "background": "opaque",
      "output_format": "png",
      "quality": "high",
      "size": "1024x1024",
      "usage": {
        "input_tokens": 10,
        "input_tokens_details": { "cached_tokens": 0, "text_tokens": 10, "image_tokens": 0 },
        "output_tokens": 7033,
        "output_tokens_details": { "text_tokens": 0, "image_tokens": 7033 },
        "total_tokens": 7043
      }
    },
    "completionTokens": 7043
  }
}

usage 字段含义：

字段	说明
`input_tokens`	输入 token 总数
`input_tokens_details.cached_tokens`	缓存命中的输入 token
`input_tokens_details.text_tokens`	提示词 token
`input_tokens_details.image_tokens`	参考图 token；文生图通常为 0
`output_tokens`	输出 token 总数
`output_tokens_details.image_tokens`	生成图片 token
`output_tokens_details.text_tokens`	输出文本 token，图片生成通常为 0
`total_tokens`	总 token 数

计费以 output.usage 为准：建单时按预估用量冻结，完成后按实际的文本输入 / 图片输入 / 图片输出 token 多退少补，失败任务全额解冻。

少数情况下只能拿到总量、拿不到细分，此时 input_tokens_details / output_tokens_details 可能为 0 或整体缺省，
而 input_tokens / output_tokens / total_tokens 始终按实际结算口径返回。请按可选字段做兼容解析。

错误响应

异步模式（默认）下两个端点的错误都沿用平台统一错误体（HTTP 状态码恒为 200，以 code 判断）；
同步模式（async=false）的错误体见下文「同步模式」。

{
  "code": 10002,
  "msg": "参数错误: resolution 仅支持 1K、2K、4K"
}

code	说明
0	成功
10002	参数缺失或格式错误 / 不支持的 model
10005	API Key 无效或缺失
30003	任务不存在
40001	余额不足
90003	服务器内部错误

任务本身失败（如内容不符合规范）不体现在建单响应里，而是查询时 data.status 为 failed，
并带 data.errorCode / data.errorMsg。

同步模式（`async=false`）

两个端点都支持传 async=false 切换为同步：服务端阻塞等待出图，直接返回 OpenAI 标准图片响应。

curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A beautiful sunset over the ocean, oil painting style",
    "size": "16:9",
    "async": false
  }'

响应体（与异步模式完全不同，这是 OpenAI 标准图片响应）：

{
  "created": 1778394000,
  "data": [
    { "url": "https://.../output_001.png" }
  ]
}

传 response_format=b64_json 时 data 项改为 {"b64_json":"..."}。

同步模式的错误响应沿用 OpenAI 标准错误体，并使用真实 HTTP 状态码（不再恒为 200）：

{
  "error": {
    "message": "参数错误: resolution 仅支持 1K、2K、4K",
    "type": "invalid_request_error"
  }
}

HTTP	type	说明
400	`invalid_request_error`	参数缺失或格式错误 / 不支持的 model
401	`authentication_error`	API Key 无效或缺失
402	`insufficient_quota`	余额不足
500	`generation_error`	任务执行失败（如内容不符合规范）
504	`timeout_error`	等待超过 10 分钟仍未出图；任务未取消，`error.code` 即 `taskId`，可继续用查询端点取结果

Python 接入示例

异步（默认，推荐）

拿到 data.taskId 后轮询 GET /v1/images/generations/{taskId}：

import requests, time

base = "https://api.apiverse.ai"
headers = {"Authorization": "Bearer your_api_key_here"}

def wait_result(task_id):
    while True:
        data = requests.get(f"{base}/v1/images/generations/{task_id}", headers=headers).json()["data"]
        if data["status"] != "processing":
            return data
        time.sleep(3)

# 文生图 / 图生图
task_id = requests.post(
    f"{base}/v1/images/generations",
    headers=headers,
    json={
        "model": "gpt-image-2",
        "prompt": "A beautiful sunset over the ocean, oil painting style",
        "size": "16:9",
        "resolution": "2k",
    },
).json()["data"]["taskId"]
print(wait_result(task_id).get("result"))

# 图片编辑（上传文件）
with open("/path/to/cat.png", "rb") as f:
    task_id = requests.post(
        f"{base}/v1/images/edits",
        headers=headers,
        data={"model": "gpt-image-2", "prompt": "给猫戴上一顶生日帽", "size": "1024x1024"},
        files={"image": f},
    ).json()["data"]["taskId"]
print(wait_result(task_id).get("result"))

同步（OpenAI SDK 直连）

async=false 时响应体即 OpenAI 标准格式，可直接用官方 SDK。async 走 extra_body 传入：

from openai import OpenAI

client = OpenAI(
    api_key="your_api_key_here",
    base_url="https://api.apiverse.ai/v1",
    timeout=900,  # 同步模式需放宽超时
)

# 文生图
img = client.images.generate(
    model="gpt-image-2",
    prompt="A beautiful sunset over the ocean, oil painting style",
    size="1024x1024",
    extra_body={"async": False, "resolution": "2k"},
)
print(img.data[0].url)

# 图片编辑
with open("/path/to/cat.png", "rb") as f:
    edited = client.images.edit(
        model="gpt-image-2",
        prompt="给猫戴上一顶生日帽",
        image=f,
        extra_body={"async": False},
    )
print(edited.data[0].url)

最佳实践

1. 超时设置

异步模式（默认）下两个端点均建单即返回，客户端超时按普通接口设置即可（图片编辑需考虑上传原图的耗时）。
同步模式（async=false）需把客户端超时放宽到 10 分钟以上；服务端等待超过 10 分钟会返回 504，
此时任务未取消，可用 error.code 里的 taskId 继续查询。

2. 轮询策略

（异步模式）建议：前 30 秒每 3 秒查询一次，30 秒后每 5 秒一次。
生产环境建议改用 callback_url 回调，可显著降低查询请求量。

3. Prompt 编写建议

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

GPT Image 2 图片生成 API（v1 / OpenAI 兼容协议）对接文档

概述

认证方式

快速开始

cURL 示例

接口说明

创建图片生成任务

请求参数

请求示例

响应参数（建单成功）

响应示例（建单成功）

图片编辑

cURL 示例

请求参数（multipart/form-data）

响应参数（建单成功）

响应示例（建单成功）

查询图片任务

gpt-image-2-official 的 token 用量

错误响应

同步模式（async=false）

Python 接入示例

异步（默认，推荐）

同步（OpenAI SDK 直连）

最佳实践

1. 超时设置

2. 轮询策略

3. Prompt 编写建议

`gpt-image-2-official` 的 token 用量

同步模式（`async=false`）