GPT Image 2 API 参数详解：尺寸、分辨率、宽高比与质量

GPT Image 2 API 用 model 接收模型名，用 size 以 WIDTHxHEIGHT 像素的形式接收输出尺寸，用 quality 接收质量（low、medium、high 或 auto）。API 没有 resolution 或 aspect_ratio 字段。要得到 4K 的 16:9 图像，就发送 "size": "3840x2160"。尺寸必须是 16 的倍数，两条边都不超过 3840 像素，宽高比在 1:3 到 3:1 之间，总像素在 655,360 到 8,294,400 之间。

本指南逐一介绍会改变画面的每个参数，给出应发送的确切取值，以及错误取值返回的报错。下面的每个错误都在线上 API 上核对过。

GPT Image 2 在 API 中的模型名是什么？

使用 gpt-image-2 或 gpt-image-2-official。两者是同一个模型，字段也相同；gpt-image-2 每交付一张图收一个固定价，gpt-image-2-official 按每次出图报告的 token 计费。

标题里的名字不能当作模型 ID 使用。gpt-image-2.0、GPT Image 2 或 chatgpt-images-2 都会返回 HTTP 400，错误码 20002。

如何设置分辨率和宽高比？

用 size，单位是像素。先选定想要的宽高比和像素规模，再发送换算出的宽和高：

这与 Playground 在你选择宽高比和 1K、2K 或 4K 预设时使用的换算完全相同。方形 4K 止步于 2880x2880，因为 3840 像素的正方形会超过总像素上限。

size: "auto" 把尺寸交给模型决定。它是默认值，也很方便，但当输出需要匹配某个版式、或者多张图需要彼此一致时，请设置明确的尺寸。

OpenAI 将 2560×1440 以上的输出描述为实验性的。在这里的限制范围内它会被接受，但更大的画布并不保证更多的细节。

哪些 size 取值会被拒绝？

注意最后两行。未知字段会被拒绝，但错误信息不会指出是哪个字段。如果你收到 20001，而错误信息是通用的 “Check the parameters against the API documentation”，请检查是否带了 API 不接受的字段，例如 resolution、aspect_ratio 或 response_format。

应该选择哪种质量？

quality 接受 low、medium、high 和 auto。档位越高，耗时越长，保留的细节越精细。xhigh 和 max 仅属于 GPT Image 2.5；把它们发给 GPT Image 2 会返回 20001，错误信息会指出 quality。

一个实用的流程：构图还在变化时用 low 出草稿，用 medium 检查纹理和小字，最终成图用 high。在 gpt-image-2 上，每个档位价格相同。在 gpt-image-2-official 上，档位越高报告的输出 token 越多，因此费用更高。价格指南给出了具体数字。

auto 让模型自行选择档位。对比多次运行时请设置明确的值，否则两个「相同」的请求可能以不同的档位出图。

格式和背景由什么控制？

• output_format：png（默认）或 jpeg。不提供 WebP 输出；传 webp 会返回 20001，错误信息会指出 output_format。
• output_compression：0 到 100，仅在 jpeg 时可用。
• background：auto、opaque 或 transparent。透明背景需要 png；transparent 配合 jpeg 会返回 20001，错误信息会指出 background。
• n：每个请求 1 到 10 张图。按实际交付的图像数量计费。
• moderation：auto 或 low。

参考图和遮罩如何传入？

以 URL 形式传入，绝不接受文件或 base64。images 接受 1 到 16 个形如 {"image_url": "https://..."} 的对象，传入它就会把请求变成编辑。mask 接受一个同样形状的对象：一张与第一张参考图尺寸相同的 PNG，其中透明区域标出要修改的部分。API 文档列出了文件限制。

常见问题

GPT Image 2 支持 4K 吗？

支持，但要在上述限制之内。16:9 的 3840x2160 和 9:16 的 2160x3840 是最大的画幅，2880x2880 是最大的正方形。

可以发送宽高比而不是像素吗？

API 不支持。请先用上面的表格或 Playground 把宽高比换算成 WIDTHxHEIGHT 尺寸，Playground 会在提交前显示确切的尺寸。

默认的尺寸和质量是什么？

两者默认都是 auto，由模型决定。需要可预期的输出时，请发送明确的值。

发送像素、设定质量、读懂错误信息

几乎所有参数问题都属于三种情况之一：把宽高比当作尺寸发送、带了 API 不接受的字段、或者取值超出限制。第一种和第三种，错误信息会指出具体字段；错误信息是通用提示、没有指出任何字段，则属于第二种。集成期间，把本页和 GPT Image 2 API 文档放在一起参考。