快速结论
- 调用入口是 POST /v1/images/generations，请在请求体中设置 model=gpt-image-2。
- 支持 prompt 文生图，也支持通过 reference_images 传参考图 URL 做参考图生成或编辑。
- 参考图只支持 URL，本地图片需要先调用上传接口，不能直接传 base64。
- 接口采用异步任务模式，先返回任务 ID，再通过图片任务状态接口查询结果。
关键参数
- model | string | 必填 | gpt-image-2 | - | 固定使用 gpt-image-2 作为模型标识。
- prompt | string | 必填 | - | - | 图片生成或编辑的主提示词。
- size | string | 可选 | 1024x1024 | 按官方文档与 resolution 组合取值 | 输出尺寸参数，需要与 resolution 组合满足文档约束。
- resolution | string | 可选 | 1024 | 1024 | 1536 | 2048 | 输出分辨率；可选值与 size 组合必须满足文档限制。
- reference_images | string[] | 可选 | - | URL 数组 | 参考图 URL 数组，用于参考图生成或编辑。本地图片需先上传，不能直接传 base64。
- image_urls | string[] | 可选 | - | URL 数组（兼容字段） | 兼容字段，旧调用可继续使用；新接入建议优先使用 reference_images。
- response_format | string | 可选 | url | url | b64_json | 返回结果格式；中文 docs 当前推荐使用 url。
常见错误
- 400 invalid_request_error: 触发=缺少必填字段，或 size 与 resolution 组合不合法。; 修复=按官方文档校验 model、prompt、size、resolution、response_format 的字段和值。; 重试=修正参数后重试，不建议盲重试。
- 400 invalid_reference_images: 触发=直接传 base64、传入本地路径、或 reference_images 不是 URL。; 修复=先调用上传图片接口，拿到 URL 后再传给 reference_images。; 重试=修正参考图输入后重试。
- 401 authentication_error: 触发=Authorization 头缺失或 API Key 无效。; 修复=检查 Bearer Token 格式和密钥权限范围。; 重试=修复鉴权后再重试。
- 429 rate_limit_exceeded: 触发=请求频率、并发或当前额度命中上游限流策略。; 修复=先做指数退避重试，并检查当前请求节奏、并发设置和额度使用情况。; 重试=建议 1s/2s/4s 退避并加入抖动；连续触发时再收紧提交节奏。
