很多开发者在接入 gpt-image-2 的图片编辑接口时都会卡在同一个问题上：翻遍 images/edit 的 API Reference 页面，只看到"GPT image 模型最多可传 16 张图"这一句，却找不到单张图片的大小限制。是没有限制？还是文档漏写了？
答案是：限制存在，而且很明确——单张图片必须小于 50MB，支持 PNG、WebP、JPG 三种格式。只不过这条规则没有写在 Reference 页面的参数表里，而是写在另一份 Image Generation 使用指南文档中，两份文档的信息割裂让不少人扑了个空。
本文会把 gpt-image-2 API 的图片上传限制一次性讲透：数量、大小、格式、mask 规则、分辨率约束，以及一个比 50MB 上限更值得关注的实战问题——为什么我们不建议你真的传 50MB 的图。
gpt-image-2 API 图片上传限制：官方完整规格
先把结论放在最前面。gpt-image-2 通过 v1/images/edits 端点接收输入图片，完整的官方限制如下表所示。
gpt-image-2 图片上传限制速查表
| 限制项 | 官方规格 | 文档出处 |
|---|---|---|
| 单次最多图片数 | 16 张（GPT image 系列模型） | API Reference：images/edit |
| 单张图片大小 | < 50MB | Image Generation 使用指南 |
| 支持格式 | PNG、WebP、JPG | Image Generation 使用指南 |
| 传图方式 | image_url 或 file_id 二选一 |
API Reference：images/edit |
| mask 蒙版 | 与原图同格式同尺寸、< 50MB、必须含 alpha 通道 | Image Generation 使用指南 |
| 单次生成数量 n | 1-10 张 | API Reference：images/edit |
也就是说，理论上一次 edit 请求最多可以携带 16 张接近 50MB 的图片。但"理论上限"和"工程上该怎么用"是两回事，后文会展开。
这里有个容易踩的坑值得单独说明：新版 API 的 images 参数接收的是对象数组，每个对象提供 image_url 或 file_id 其中之一。file_id 来自 Files API 预上传，适合复用的素材库场景；image_url 支持公网地址或 base64 data URL，适合一次性请求。两种方式的 50MB 限制是一致的。
🎯 快速验证建议：如果你不确定自己的图片是否会触发限制，最直接的方式是发一个真实请求看报错信息。我们建议通过 API易 apiyi.com 的 OpenAI 兼容接口做这类边界测试，平台的日志面板能完整看到请求体大小和错误详情，排查比裸调官方接口更直观。
gpt-image-2 上传大小为什么在文档里"找不到"
回到开头的疑问：为什么 Reference 页面只写了 16 张，不写大小？这其实是 OpenAI 文档结构的设计取舍。images/edit 的 Reference 页面是按"参数 Schema"组织的，images 参数在 Schema 层面只是一个对象数组，数量上限属于数组约束，所以被写了进去；而文件大小、格式属于"运行时校验"，被归类到了 Image Generation 指南的叙述性文字里。
类似的"藏在指南里"的规则还有几条，做图片编辑功能前最好一并确认：
- mask 蒙版三要求：必须与被编辑图片同格式、同尺寸，文件同样小于 50MB，且必须包含 alpha 通道——用 JPG 当 mask 是最常见的报错原因，因为 JPG 没有 alpha 通道。
- 分辨率不是任意的：gpt-image-2 的
size参数支持自定义分辨率，但有硬约束——最长边不超过 3840px，宽高都必须是 16px 的倍数，宽高比不超过 3:1，总像素需落在 655,360 到 8,294,400 之间。 - 输入图会计费：edit 请求中的参考图按图像输入 token 计费，
input_fidelity: high时消耗的输入 token 会明显增加。
gpt-image-2 分辨率与 size 参数约束
| 约束维度 | 规则 | 示例 |
|---|---|---|
| 最长边 | ≤ 3840px | 3840×2160（4K 横版）可用 |
| 边长对齐 | 宽高均为 16px 倍数 | 1024、1536、2048 均合法 |
| 宽高比 | ≤ 3:1 | 2048×1152 合法，3072×1024 合法 |
| 总像素 | 655,360 – 8,294,400 | 低于 768×854 量级会被拒 |
| 常用预设 | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | 竖版同理对调 |
如果你的业务需要频繁在不同分辨率之间切换，建议把这张约束表做成请求前的本地校验，在客户端就拦截非法尺寸，比等 API 返回 400 错误节省一次往返。在 API易 apiyi.com 的文档中心也整理了 gpt-image-2 的参数校验清单，可以直接对照实现。
gpt-image-2 实战：50MB 是上限，1.5MB 才是甜点
知道了 50MB 的硬上限，更重要的问题是：实际工程里应该传多大的图？我们的建议是单张控制在 1.5MB 左右，尽量不超过 5MB。这不是拍脑袋，背后有三层原因。
第一层是 base64 膨胀。如果你用 data URL 方式内嵌图片，base64 编码会让体积膨胀约 33%——一张 40MB 的原图编码后接近 53MB，叠加 JSON 结构后请求体可能直接超限。16 张图全用 base64 内嵌时，这个问题会被放大 16 倍，大体积素材务必改用 file_id 预上传通道。
第二层是传输与解码耗时。超过 5MB 之后，上传时间加服务端解码时间呈非线性增长，在网络波动时还容易触发超时重试，反而拖慢整体出图速度。1.5MB 左右的图片在普通家庭宽带下 1-2 秒即可完成上传，是稳定性和质量的平衡点。
第三层是画质收益递减。gpt-image-2 在处理输入图时会先做内部预处理，输入分辨率远超输出分辨率时，多出来的像素基本被浪费。一张 3840px 长边、压缩到 2MB 以内的 JPG，与 40MB 的无损 PNG 在编辑效果上几乎没有可感知差异，成本和耗时却差一个量级。
gpt-image-2 图片大小实践建议
| 原图情况 | 建议处理 | 预期效果 |
|---|---|---|
| < 1.5MB | 直接上传 | 最佳速度与稳定性 |
| 1.5MB – 5MB | 可直接传，建议转 JPG/WebP | 速度可接受 |
| 5MB – 20MB | 压缩至长边 ≤ 3840px + 质量 85 | 画质几乎无损，耗时大幅下降 |
| 20MB – 50MB | 必须压缩，改用 file_id 上传 | 避免 base64 膨胀超限 |
| > 50MB | 超出硬上限，必须压缩 | 否则直接报错 |
💡 批量场景提示：电商抠图、批量风格化这类高并发场景，建议在上传前用 sharp 或 Pillow 统一做"长边 3840px + JPG 质量 85"的预压缩。我们在 API易 apiyi.com 的企业客户案例中验证过，这一步平均能把单次 edit 请求的端到端耗时降低 40% 以上，且画质投诉为零。
gpt-image-2 API 快速上手：多图编辑代码示例
gpt-image-2 走标准 OpenAI 接口协议，下面是一个携带多张参考图的最简编辑示例，通过 API易转发只需替换 base_url：
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # API易统一接口
)
def to_data_url(path):
with open(path, "rb") as f:
b64 = base64.b64encode(f.read()).decode()
return f"data:image/jpeg;base64,{b64}"
result = client.images.edit(
model="gpt-image-2",
image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
prompt="将产品图融合参考图的霓虹赛博风格,保持产品主体不变",
input_fidelity="high", # 高保真保留输入细节,输入 token 消耗更多
size="2048x2048",
quality="high"
)
print(result.data[0].b64_json[:64]) # 返回 base64 编码的结果图
几个参数要点：input_fidelity 设为 high 时人脸、Logo 等细节保留度显著提升，代价是图像输入 token 计费增加；quality 与 size 是决定输出成本的两个主要杠杆；n 参数单次最多生成 10 张。计费方面，gpt-image-2 按 token 计价：文本输入 $5/M，图像输入 $8/M（缓存命中 $2/M），图像输出 $30/M。换算成单张图，1024×1024 的 low 档约 $0.006，medium 档约 $0.05，high 档约 $0.21，输出侧永远是成本大头。
另外注意官方的速率限制按账户层级区分：Tier 1 仅 5 张图/分钟，Tier 4 为 150 张/分钟，Tier 5 为 250 张/分钟。新账户层级低，批量任务很容易撞限流。通过 API易 apiyi.com 这类聚合平台调用可以绕开单账户层级限制，适合需要大并发出图的生产环境。
gpt-image-2 与上一代模型的上传限制差异
如果你的项目是从 gpt-image-1 或 DALL·E 2 迁移过来的，还需要留意几处代际差异。最大的变化在 DALL·E 2 到 GPT image 系列之间：DALL·E 2 的 edit 接口只接受一张正方形 PNG，且必须小于 4MB；到了 GPT image 系列，才放宽到 16 张、50MB、三种格式。很多老项目里写死的"PNG + 4MB 压缩"预处理逻辑，迁移后其实可以大幅简化。
gpt-image-2 相对 gpt-image-1 的升级则主要体现在分辨率和成本上。gpt-image-1 只支持 1024×1024、1536×1024、1024×1536 三种固定输出；gpt-image-2 开放了自定义分辨率，最高支持到 3840px 长边的 4K 输出。价格方面，gpt-image-2 的图像输入从 $10/M 降到 $8/M，图像输出从 $40/M 降到 $30/M，还新增了 $2/M 的缓存命中档，重复参考图场景的成本下降明显。
gpt-image-2 与历代模型上传限制对比
| 对比项 | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| 输入图数量 | 1 张 | 最多 16 张 | 最多 16 张 |
| 单张大小上限 | < 4MB | < 50MB | < 50MB |
| 输入格式 | 仅正方形 PNG | PNG/WebP/JPG | PNG/WebP/JPG |
| 输出分辨率 | 固定方图 | 3 种固定尺寸 | 自定义，最长边 3840px |
| 图像输出价格 | 按张计费 | $40/M tokens | $30/M tokens（缓存输入 $2/M） |
| input_fidelity | 不支持 | 支持 | 支持，高保真细节更强 |
迁移代码时基本只需要改 model 参数，但建议同步把分辨率校验和压缩策略按本文前面的约束表更新一遍。如果想先验证迁移效果再动生产代码，可以在 API易 apiyi.com 上用同一组素材分别调用两代模型，直观对比编辑质量和实际计费差异。
gpt-image-2 图片上传常见问题 FAQ
Q1：gpt-image-2 单张图片到底能传多大？
硬上限是 50MB，支持 PNG、WebP、JPG。这条限制写在 OpenAI 的 Image Generation 使用指南里，而不是 images/edit 的 Reference 参数表中，所以只看 Reference 页面会找不到。实战建议控制在 1.5-5MB，体验最优。
Q2：16 张图的数量限制是怎么用的？
images 参数最多接收 16 个图片对象，每个对象用 image_url 或 file_id 指定一张图。模型会把多张图作为联合参考，适合"产品图 + 风格图 + 构图参考"的组合编辑场景。注意 16 张是输入上限，输出数量由 n 参数控制，上限 10 张。
Q3：mask 蒙版报错"invalid mask"通常是什么原因？
九成是 alpha 通道问题。mask 必须与被编辑图片同格式、同尺寸，且必须包含 alpha 通道——JPG 不支持 alpha 通道，所以 mask 必须用 PNG。透明区域代表"允许重绘"，不透明区域保持原样。
Q4：base64 上传和 file_id 上传怎么选？
小图（< 5MB）、一次性请求用 base64 data URL 最省事；大图或需要多次复用的素材，用 Files API 预上传拿 file_id，既避开 base64 的 33% 体积膨胀，又能跨请求复用。如果拿不准，可以在 API易 apiyi.com 控制台两种方式各跑一次，对比实际耗时后再定方案。
总结：gpt-image-2 上传限制的三个关键数字
回到最初的问题，gpt-image-2 图片编辑 API 的上传限制可以浓缩成三个数字：16 张（单次输入图数量上限，写在 Reference）、50MB（单张大小上限，写在使用指南）、1.5MB（工程实践的甜点大小）。文档把数量和大小拆在两个页面，是造成"只看到 16 张"困惑的根源。
落地建议也很简单：上传前统一压缩到长边 3840px 以内、JPG 质量 85 左右；mask 永远用带 alpha 通道的 PNG；大素材走 file_id 通道。把这三件事做成请求前的固定预处理，基本可以告别上传相关的所有报错。
如果你需要在国内稳定调用 gpt-image-2，或者想把限流上限提到生产级，可以通过 API易 apiyi.com 的统一接口接入，兼容 OpenAI SDK 原生写法，改一行 base_url 即可迁移。
参考资料：OpenAI API Reference: developers.openai.com/api/reference/resources/images/methods/edit
作者: APIYI Team
专注 AI 大模型 API 聚合与最佳实践，更多模型评测与接入指南欢迎访问 API易 apiyi.com。
