参数与错误

这一页集中说明同步与异步字段的对应关系、请求限制和错误处理。具体参数是否生效、可选值和生成数量上限仍取决于所选模型。

输出参数映射

含义	同步字段	异步 JSON 字段	异步 multipart 字段
生成数量	n	output.count	n
图片尺寸	size	output.size	size
质量	quality	output.quality	quality
输出格式	output_format	output.format	output_format
压缩比例	output_compression	output.compression	output_compression
背景模式	background	output.background	background

异步 output.count 的接口范围为 1 到 10，output.compression 的范围为 0 到 100。模型本身可能有更严格的限制。

gpt-image-2 自定义分辨率

Azure 渠道的 gpt-image-2 可以通过 size、异步 JSON 的 output.size 或异步 multipart 的 size 传入自定义 宽x高。尺寸必须同时满足：

max(width, height) < 3840
width % 16 == 0
height % 16 == 0
max(width, height) / min(width, height) <= 3
655360 <= width * height <= 8294400

3840 不是有效边长

OpenAI 当前官方原文要求最长边严格小于 3840px，因此 3840x1280 不符合规则。最长可用的 16 倍数边长是 3824px。adobe-gpt-image-2-count 和 gpt-image-2-count 使用各自渠道的尺寸范围，不要用这组官方通道规则推断。

以接近 2172x724 的 3:1 截图画幅为例：

尺寸	是否有效	说明
2172x724	否	两边都不是 16 的倍数
2160x720	是	最接近原尺寸的实用 3:1 规格
3072x1024	是	更高清的 3:1 规格，总像素仍低于实验区间阈值
3792x1264	是	接近上限的精确 3:1 规格，属于实验区间
3824x1280	是	比例约为 2.99:1，属于实验区间
3840x1280	否	最长边等于 3840

官方提示：总像素超过 3,686,400（2560x1440）时，应将输出视为实验性结果，生成稳定性可能下降。这里按总像素判断，不是单独比较宽或高。

同步文生图示例：

curl -sS "$SUPERTOKEN_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "宽幅产品界面概念图，主体信息集中在中央安全区",
    "n": 1,
    "size": "2160x720",
    "quality": "medium"
  }' | jq .

官方规则来源：GPT Image Generation Models Prompting Guide。

异步任务字段

字段	必填	说明
model	是	当前账号可用的模型名称
operation	是	generation 或 edit
input.prompt	是	生成或编辑提示词
input.images	编辑时是	URL 对象数组，格式为 [{"url":"https://..."}]
input.mask	否	单个 Mask URL 对象
output	否	数量、尺寸、质量、格式、压缩和背景参数
client_reference_id	否	业务侧关联 ID，最长 191 个字符
metadata	否	自定义 JSON 对象，会随任务返回

上传限制

项目	限制
参考图片数量	最多 10 张
Mask 数量	最多 1 张
单个文件大小	最大 20 MiB
multipart 请求总大小	最大 100 MiB
文件格式	PNG、JPEG、WebP
URL 输入	可公开访问的 HTTP/HTTPS 图片直链

不同模型可能有更严格的图片数量、尺寸、格式或参数限制，最终以所选模型的实际响应为准。

请求格式速查

场景	正确字段	不要使用
同步 URL 编辑	image: ["https://..."]	images: [{"image_url":"..."}]
同步本地文件	multipart 重复 image	把本地路径放进 JSON
同步 Base64 编辑	image: [{"b64_json":"..."}]	只传没有数据字段的对象
异步 URL 编辑	input.images: [{"url":"..."}]	同步接口的顶层 image
异步本地文件	multipart 重复 image	JSON 中传本地文件路径

任务状态

状态	是否终态	含义
queued	否	任务已创建并等待执行
in_progress	否	任务正在执行
succeeded	是	从 result.images[] 读取图片
failed	是	从 error 读取失败原因

错误对象

异步与资源接口使用统一错误对象：

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "input.images is required for edit tasks",
    "param": "input.images",
    "request_id": "request_example123"
  }
}

终态失败任务的 error 位于任务对象内。例如内部图片渠道暂时不可用时，公开错误会被统一包装，不会包含渠道、子分组、内部余额或上游 Request ID：

{
  "status": "failed",
  "error": {
    "code": "524",
    "message": "Image generation service is temporarily unavailable. Please try again later.",
    "retryable": true
  }
}

这里的 "524" 是字符串形式的业务错误码，不是 HTTP 524。查询一个已经失败的异步任务仍会得到正常的任务查询响应，并通过 status: "failed" 表示终态。

HTTP 状态	常见原因	处理建议
400	字段格式错误、编辑任务缺少图片、URL 无效	检查 error.param 和请求结构
401 / 403	密钥无效、密钥类型错误或没有资源权限	核对 sk-... 与 ak_... 的使用位置
409	同一 Idempotency-Key 对应了不同请求	为新请求生成新的幂等键
413	单文件或总请求大小超限	压缩图片或减少单次上传数量
429	请求频率或额度受限	降低频率并按返回信息重试
502 / 503	暂时无法完成请求	保留请求 ID，按业务策略有限重试

对于异步失败任务，仅当 error.retryable 为 true 时建议自动重试。终态失败任务已经固定在原 Idempotency-Key 下，复用原 Key 只会返回同一个失败任务；发起新的尝试时必须生成新的 Idempotency-Key。网络中断且尚未确认创建结果时，才复用原 Key 查询或重放原请求，以避免重复创建。

常见问题

URL 编辑为什么提示缺少 Base64 字段？

同步接口使用顶层 image 字段：

{
  "image": [
    "https://img.example.com/reference-1.png",
    "https://img.example.com/reference-2.png"
  ]
}

不要传 images[].image_url。该对象不是当前同步编辑接口支持的 URL 结构，会进入 Base64 对象校验并提示缺少 b64_json、base64、data 或 image。

curl 返回 HTTP_STATUS=000 是 API 错误吗？

不是。HTTP_STATUS=000 表示 curl 没有收到 HTTP 响应，例如 DNS、TLS 握手或本地网络连接失败。先处理 curl 输出的连接错误；只有收到 4xx 或 5xx 时，才是服务端已经返回了 HTTP 错误。

为什么异步查询不能使用模型 Token？

创建任务属于模型调用，使用普通模型 API Token；任务查询、列表和预上传属于资源访问，使用资源 API Key。两种密钥的权限范围不同。

从旧版路径迁移

旧版文档仍然保留，新项目建议使用新版路径：

旧版路径	新版路径
/image-wrapper/v1/images/generations	/v1/images/generations
/image-wrapper/v1/images/edits	/v1/images/edits

迁移同步接口时，主要调整 Base URL 路径与模型名称；需要任务化处理时，改用 /v1/image/tasks 及资源管理中心的查询接口。已有项目可继续查看旧版 GPT-Image-2 文档。

下一步

• 同步生成与编辑
• 异步任务
• Webhook 完成通知
• Python 与 Node.js 代码示例