gpt-image-2
文本生图、参考图编辑、图生图与局部重绘
能力概览
只需提示词即可生成写实图、插画、海报与商品图。
根据一张或多张参考图生成新的画面。
最多组合 16 张参考图，适合商品与场景合成。
参考图自动按高保真方式处理。
用带 Alpha 通道的蒙版指定主要修改区域。
提示词1–32,000 字符
生成数量n 为 1–10
参考图1–16 张
参考图文件每张小于 50 MB
蒙版PNG，小于 4 MB
生成与编辑图像
文生图
https://www.yunqiai.chat/v1/images/generations只传提示词时使用 Images Generations，请在 JSON 请求体中填写完整模型 ID。
参考图编辑
https://www.yunqiai.chat/v1/images/edits图生图使用 Images Edits，并通过 multipart/form-data 上传参考图。
文生图参数
| 参数 | 类型 | 说明 |
|---|---|---|
model必填 | string | gpt-image-2 |
prompt必填 | string | 1–32,000 字符 |
size | string | auto，或符合尺寸约束的 WIDTHxHEIGHT；无需另传 resolution |
quality | string | low、medium、high、auto；默认 auto |
n | integer | 1–10；生成数量会直接影响费用 |
output_format | string | png、jpeg、webp；默认 png |
output_compression | integer | 0–100；仅 jpeg / webp，默认 100 |
background | string | auto 或 opaque；默认 auto |
moderation | string | auto 或 low；默认 auto |
stream | boolean | 是否流式返回；GPT Image 模型支持 |
partial_images | integer | 0–3；仅流式请求，默认 0 |
user | string | 可选终端用户标识，用于滥用监测 |
gpt-image-2 尺寸规则
输出比例不限定为 1:1、3:2、2:3。通过 size 直接填写宽高，只要满足下面的像素约束即可。
| 约束 | 范围 | 说明 |
|---|---|---|
| 宽高步进 | 16 px | 宽和高都必须是 16 的倍数 |
| 输出比例 | 1:3–3:1 | 长边与短边之比不超过 3:1 |
| 最长边 | ≤ 3840 px | 横图和竖图使用同一限制 |
| 总像素 | 655,360–8,294,400 | 在范围内可自由组合宽高 |
常用尺寸
| size | 输出比例 | 适合场景 |
|---|---|---|
1024x1024 | 1:1 | 方形图片 |
1536x1024 | 3:2 | 横向图片 |
1024x1536 | 2:3 | 竖向图片 |
2048x2048 | 1:1 | 2K 方形图片 |
2048x1152 | 16:9 | 2K 横图 |
3840x2160 | 16:9 | 最大横图 |
2160x3840 | 9:16 | 最大竖图 |
质量怎么选
quality 控制画面的细节程度。质量越高，通常生成时间越长、费用也越高；大多数任务使用标准质量即可。
| quality | 特点 | 适合场景 |
|---|---|---|
auto | 自动选择 | 不想手动指定质量时使用 |
low | 速度最快、费用最低、细节较少 | 快速草稿、构图预览 |
medium | 速度、费用与细节较均衡 | 日常生图与常规编辑 |
high | 细节最丰富、生成更慢、费用较高 | 复杂场景、精细纹理与大量细节 |
参考图、多图与蒙版
gpt-image-2 通过 Images Edits 接收参考图。多张图片重复填写 image[]；蒙版只作用于第一张图。
| 参数 | 类型 | 说明 |
|---|---|---|
model必填 | string | gpt-image-2 |
image / image[]必填 | file | file[] | 通过 multipart/form-data 上传 1–16 张参考图 |
mask | file | 可选 PNG 蒙版，小于 4 MB；与第一张参考图尺寸一致并含 Alpha 通道 |
prompt必填 | string | 1–32,000 字符；说明需要保留和修改的画面内容 |
其余可选参数与上方文生图参数相同；编辑请求改用 multipart/form-data。
| 项目 | 范围 | 说明 |
|---|---|---|
| 参考图 | 1–16 张 | 可组合人物、商品、背景与风格素材 |
| 参考图文件 | PNG、JPG、WebP | 每张小于 50 MB |
| 蒙版 | PNG，小于 4 MB | 与第一张参考图尺寸一致并含 Alpha 通道 |
| 主体保持 | 自动高保真 | 无需额外参数 |
curl --request POST \
--url https://www.yunqiai.chat/v1/images/edits \
--header "Authorization: Bearer YOUR_API_KEY" \
--form "model=gpt-image-2" \
--form "image[]=@./scene.png" \
--form "image[]=@./product.png" \
--form "mask=@./mask.png" \
--form "prompt=把第二张图中的商品放到第一张场景中，保持商品外观不变" \
--form "size=1536x1024"Base64 返回值
逐项遍历完整 data[]。每一项可能提供可下载的 url，也可能直接提供 b64_json；下面的解析器兼容两种返回形式，并会保存所有图片。
import base64
import json
import sys
from pathlib import Path
import requests
result = json.load(sys.stdin)
for index, item in enumerate(result.get("data", []), start=1):
output_path = Path(f"result-{index}.png")
if item.get("b64_json"):
image_bytes = base64.b64decode(item["b64_json"])
elif item.get("url"):
download = requests.get(item["url"], timeout=(10, 60))
download.raise_for_status()
image_bytes = download.content
else:
raise ValueError(f"data[{index - 1}] 没有 url 或 b64_json")
output_path.write_bytes(image_bytes)
print(output_path)将请求返回保存为 response.json 后运行 python save_images.py < response.json。编辑接口的输入仍使用 multipart 文件上传；已有 Base64 输入时，先解码成图片文件。
请求示例
以下示例只传文字提示词，通过 Images Generations 直接生成图片。
curl --request POST \
--url https://www.yunqiai.chat/v1/images/generations \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "gpt-image-2",
"prompt": "雨后的未来城市，霓虹倒影，电影感构图",
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
"n": 1
}'响应结构
{
"created": 1785987000,
"data": [
{
"b64_json": "BASE64_IMAGE_DATA"
}
],
"output_format": "png",
"quality": "medium",
"size": "1024x1024"
}流式、错误与超时
| 情况 | 客户端处理 |
|---|---|
| 同步请求 | 连接超时可设为 10 秒，读取超时从 300 秒起设置 |
| 流式图片 | stream: true 时，中间图和最终图都通过 image_generation.partial_image 返回；按 partial_image_index 保存并解码 b64_json，流正常结束后以最后一张为最终图 |
| 408、429、5xx | 读取 Retry-After，使用带随机抖动的指数退避并限制重试次数 |
| 400、401、403、404 | 不要自动重试；检查错误正文、鉴权、模型、文件与参数 |
协议参考
本页示例按 YunQi AI 的模型 ID、接口路径和参数格式编写；以下链接提供对应协议的字段说明。