GPT Image API 怎么调用？参数、返回格式、图片编辑与报错排查

图片生成2026-11-15

ChatGPT 网页里的「创建图片」按钮，和开发者调用的图片 API 不是同一个入口。网页端按账号套餐用，API 则按调用计费，适合接进自己的网站、脚本和自动化流程。这篇讲怎么用 OpenAI 兼容的图片接口调用 gpt-image 系列模型。

关于模型名

「GPT Image 2」「ChatGPT Images」和接口里的模型名称不一定一一对应。以你所用服务的模型列表为准，不要把网页上看到的型号直接抄进代码。以鹊桥为例，可以在控制台的模型列表里找图片模型；本文示例里的 gpt-image-2.6 是鹊桥当前在用的图片模型，你的分组里有没有，以控制台显示为准。

请求骨架#

图片生成走 /v1/images/generations，认证方式和文本接口一样，用 Authorization: Bearer 令牌。

curl https://cdn.5202828.xyz/v1/images/generations \
  -H "Authorization: Bearer $QUEQIAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6",
    "prompt": "一张适合技术博客封面的横图，深蓝色，主体居中，不要出现任何文字",
    "size": "1152x640",
    "quality": "medium",
    "n": 1
  }'

Python 版本，注意不假设返回里一定是 URL：

import base64, os, requests

resp = requests.post(
    "https://cdn.5202828.xyz/v1/images/generations",
    headers={"Authorization": "Bearer " + os.environ["QUEQIAO_API_KEY"]},
    json={
        "model": "gpt-image-2.6",
        "prompt": "一张适合技术博客封面的横图，深蓝色，主体居中，不要出现任何文字",
        "size": "1152x640",
        "quality": "medium",
        "n": 1,
    },
    timeout=180,
)
resp.raise_for_status()
item = resp.json()["data"][0]

if item.get("b64_json"):
    open("out.png", "wb").write(base64.b64decode(item["b64_json"]))
else:
    open("out.png", "wb").write(requests.get(item["url"], timeout=60).content)

密钥放环境变量，不要写进脚本、截图或提交到 Git。

常用参数#

参数	作用	要注意什么
`model`	指定图片模型	必须用服务实际提供的精确名称
`prompt`	描述主体、场景、构图和限制	有长度限制；想要无文字就明确写「不要出现任何文字」
`size`	图片尺寸	并不是任意值都行：像素太小会被拒绝（gpt-image 系列有最小像素要求），比例和最大边也有限制
`quality`	质量档位	档位越高通常越慢、越贵；日常插图用中档就够
`n`	一次生成几张	张数越多耗时越长，先从 1 张开始
`output_format` / `background`	输出格式、透明背景	不是所有服务都开放，先测试再用

返回格式有两种可能：b64_json（图片数据直接在响应里）或 url（临时下载地址）。链接是有有效期的，拿到后要立刻下载保存，不要把它当成永久地址存进数据库。

中文文字不要让模型来画#

让模型直接画中文标题、小字，常常会出现错字或笔画粘连。更稳的做法是分开做：

让模型生成没有文字的底图，提示词里明确写「不要出现文字、字母、数字、logo」。
标题和说明用字体在本地叠加（网页前端、设计软件，或 Pillow 这类图像库）。

这样字不会错，字体授权和品牌规范也好控制。鹊桥的 AI 日报简报图就是这么做的：配图由模型生成，所有文字由程序排版。

图片编辑#

图片编辑一般需要一张原图加一段「保留什么、改什么」的说明。输入方式可能是文件上传、图片地址或 Base64，并非每个服务都支持，上线前先拿一张没有敏感信息的样图试一遍：看格式、大小限制、结果下载方式。

提示词可以这样组织：

必须保留：主体位置、产品外形、主色、镜头角度。
只修改：把背景换成浅灰色，去掉桌面上的纸张。
不要改变：Logo 形状、产品比例。

别把身份证、合同、客户资料或没有授权的人像传给不熟悉的服务。

报错怎么排查#

状态码	常见原因	怎么办
400	参数不支持、模型名错、尺寸不合法、提示词被拒	先删掉非必要参数，对照服务文档逐项加回
401	令牌错误、复制不完整	重新复制令牌，检查环境变量
403	该分组没有这个模型的权限	换有权限的分组或令牌
404	地址或路径不对	确认是 `/v1/images/generations`，且 Base URL 的 `/v1` 没多写少写
413	图片或请求体太大	压缩、缩小尺寸
429	并发太高、限流	降低并发，退避后重试
5xx / 超时	上游波动或生成太慢	把超时设长一些（图片生成可能要几十秒），有限次重试

通用的状态码含义和带退避的重试代码，见大模型 API 常见报错怎么排查。

上线前自查#

图片模型名来自服务的模型列表，不是搜索结果。
密钥只在服务端出现。
超时设得足够长，重试次数有上限，失败时有兜底图。
并发和每日调用量有上限，避免失控产生费用。
返回的图片立刻下载保存，不依赖临时链接。
原图和输出的版权、肖像、隐私都已确认。

常见问题#

能在 ChatGPT 客户端里直接生图吗？#

客户端自带的生图工具在自定义接口下可能用不了，可以看常见问题：生图修复，或直接用鹊桥在线生图页面。

为什么我传的尺寸被拒绝了？#

图片模型对像素总量和边长都有范围要求。先用接口文档或服务示例里出现过的尺寸，再逐步调整。

返回里没有 url 字段？#

很可能是 b64_json。写代码时两种都要处理。

参考资料#

OpenAI 图片生成官方文档
事实核对参考：GPT Image 2 API 怎么调用（gpt-chinese-guide.com）

相关阅读：OpenAI 兼容接口与中转站是怎么回事