快速结论
- 调用入口是 POST /v1/images/generations，请在请求体中设置 model=gpt-image-2。
- 支持 prompt 文生图，也支持通过 reference_images 传参考图 URL 做参考图生成或编辑。
- 参考图只支持 URL，本地图片需要先调用上传接口，不能直接传 base64。
- 接口采用异步任务模式，先返回任务 ID，再通过图片任务状态接口查询结果。
- 官方公开价格按 1K / 2K / 4K 分辨率约为 $0.22 / $0.50 / $1.30 每张；ToAPIs 当前投放页固定价为 $0.015 / $0.020 / $0.025 每张，最终以账户当前价格为准。
- 按 ToAPIs 1K 档 $0.015/张估算，充值 $10 大约可继续生成 600+ 张 1K 图片；如果按 4K 档 $0.025/张估算，约可生成 400 张 4K 图片。
关键参数
- model | string | 必填 | gpt-image-2 | - | 固定使用 gpt-image-2 作为模型标识。
- prompt | string | 必填 | - | - | 图片生成或编辑的主提示词。
- size | string | 可选 | 1:1 | 1K: 1:1 | 3:2 | 2:3；2K: 1:1 | 3:2 | 2:3 | 4:3 | 3:4 | 5:4 | 4:5 | 16:9 | 9:16 | 2:1 | 1:2 | 21:9 | 9:21；4K: 4:3 | 3:4 | 16:9 | 9:16 | 2:1 | 1:2 | 21:9 | 9:21 | 输出宽高比；可选值随 resolution 档位变化。
- resolution | string | 可选 | 1K | 1K | 2K | 4K | 输出分辨率档位；需要与 size 的支持范围匹配。
- reference_images | string[] | 可选 | - | URL 数组 | 参考图 URL 数组，用于参考图生成或编辑。本地图片需先上传，不能直接传 base64。
- image_urls | string[] | 可选 | - | URL 数组（兼容字段） | 兼容字段，旧调用可继续使用；新接入建议优先使用 reference_images。
- response_format | string | 可选 | url | url | b64_json | 返回结果格式；ToAPIs 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 退避并加入抖动；连续触发时再收紧提交节奏。
