gpt-image-2 图像生成接口文档

本接口兼容 OpenAI Images API 风格，支持文生图（generations）与图生图/编辑（edits）两个端点。模型 gpt-image-2 与 gpt-image-2-count 均适用；当前接入优先使用 gpt-image-2。

---

1. 基本信息

项	值
Base URL	https://api.openfde.work/v1
模型名	gpt-image-2、gpt-image-2-count
文生图端点	POST /images/generations
图生图端点	POST /images/edits
请求格式	generations：application/json；edits：multipart/form-data
返回格式	JSON（图片为 Base64 或 URL）

---

2. 鉴权

在请求头中携带 API Key（二选一即可，推荐 Authorization）：

Authorization: Bearer YOUR_API_KEY

兼容写法：部分场景也接受 x-api-key: YOUR_API_KEY。

---

3. 请求参数

参数	类型	必填	说明
model	string	是	填写 gpt-image-2（推荐）或 gpt-image-2-count
prompt	string	是	图像描述提示词，支持中英文
size	string	是	图像尺寸，auto 或 宽x高（见第 4 节约束）
n	int	否	生成数量，默认 1
quality	string	否	图像质量：auto（默认）/ high / medium / low（见第 3.1 节）
response_format	string	否	返回方式：url 或 b64_json，不传由服务端默认
image	file	edits 必填	仅 edits 端点：作为编辑源的图片文件（multipart 上传）

3.1 quality 质量参数（参考官方 gpt-image-2）

quality 决定生成图片时消耗的图像质量：档位越高，细节、文字清晰度、精细特征越好，但延迟也越高。

取值	说明	适用场景
auto	默认，由模型按提示词自动选择最佳档位	不确定时使用
low	最快	草稿、缩略图、快速迭代
medium	速度与质量平衡	一般成品
high	细节最丰富，延迟与成本最高	最终高质量交付

提示：从 auto 显式改为 low / medium 通常能把延迟从数分钟降到数秒。参考 OpenAI 官方 gpt-image-2 文档。

---

4. size 尺寸约束（重要）

size 取值为 auto，或满足以下全部条件的自定义 宽x高：

1. 宽、高都必须是 16 的整数倍
2. 任意一边都 ≤ 3840px
3. 长边 / 短边 ≤ 3（即长宽比不超过 3:1）
4. 总像素数在 655,360 ~ 8,294,400 之间（含边界）

格式必须是小写字母 x：1024x1024 ✅；1024*1024、1024X1024 ❌

常用合法尺寸

size	说明
auto	由模型自动决定
1024x1024	方图 1:1
1536x1024	横图 3:2
1024x1536	竖图 2:3
1280x720	HD 横图 16:9
2048x2048	2K 方图
2560x1440	2.5K 横图 16:9
3840x2160	4K 横图（像素上限）
2160x3840	4K 竖图（像素上限）

非法示例

size	原因
1920x1080	1080 不是 16 的倍数
4096x2160	4096 超过最大边 3840
3840x3840	总像素超过上限
512x512	总像素低于下限
3840x1264	长宽比超过 3:1

---

5. 返回结构

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANS...",   // 当 response_format=b64_json 时
      "url": "https://.../image.png"         // 当 response_format=url 时
    }
  ]
}

• 图片数据位于 data[0]，字段为 b64_json（Base64 编码，需自行解码保存）或 url（直接下载）。
• 若返回 b64_json，用 Base64 解码后写入 .png 文件即可。

---

6. 调用示例

6.1 文生图（generations）— cURL

curl -X POST https://api.openfde.work/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cute shiba inu, flat illustration, solid background",
    "size": "1024x1024",
    "n": 1
  }'

6.2 文生图（generations）— Python

import base64
import requests

resp = requests.post(
    "https://api.openfde.work/v1/images/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "A cute shiba inu, flat illustration, solid background",
        "size": "1024x1024",
        "n": 1,
    },
    timeout=300,
)
resp.raise_for_status()
item = resp.json()["data"][0]

if item.get("b64_json"):
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    with open("output.png", "wb") as f:
        f.write(requests.get(item["url"], timeout=180).content)

6.3 图生图 / 编辑（edits）— Python（multipart）

import requests

with open("source.png", "rb") as fh:
    resp = requests.post(
        "https://api.openfde.work/v1/images/edits",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "model": "gpt-image-2",
            "prompt": "Turn the background into a starry night sky",
            "size": "1024x1024",
        },
        files={"image": ("source.png", fh.read(), "image/png")},
        timeout=300,
    )
resp.raise_for_status()

注意：edits 端点使用 multipart/form-data，所有参数以表单字段发送，源图通过 image 字段上传；不要设置 Content-Type，交给 requests 自动生成 boundary。

---

7. 错误说明

HTTP 状态	含义	建议
400	参数错误（如 size 非法、格式错误）	检查第 4 节约束
401	鉴权失败	检查 API Key
429	触发限流	按响应头 Retry-After 退避重试
5xx	服务端错误	指数退避重试

建议对 429 与 5xx 做重试（指数退避），4xx 参数错误不重试。

---