限制与生产接入建议
已确认的兼容边界
| 能力 | 当前边界 | 推荐做法 |
|---|---|---|
| GPT Image 2 AZ JSON 异步 | response_format 注入与该渠道契约冲突 | 同步调用，省略该字段 |
| 图片异步 stream=true | 没有可靠的图片 SSE 终态解析 | 使用非流式任务结果 |
| 异步 b64_json | 通常会转为托管 URL | 优先处理 URL，兼容少数 Base64 兜底结果 |
| 幂等提交 | Idempotency-Key 不保证去重 | 业务端去重，提交只发一次 |
| 多图 n>1 | 部分成功可能缺少完整失败提示，消费关联也不完整 | 生产示例固定 n=1，分别跟踪任务 |
| completed 判定 | 少数空图/异常结果也可能被标完成 | 同时校验结果、下载状态与实际图片 |
| 重启恢复 | 在途任务不保证自动续跑 | 保存 ID，超时后核查，不自动重提 |
| 取消任务 | 没有公开可用的取消 API | 客户端停止等待不等于取消服务端任务 |
| 浏览器跨域 | 未提供完整 CORS 支持 | 从自己的后端接入 |
| Gemini Special | 已不在当前公开启用清单 | 使用普通 Pro/Flash 模型 |
| 永久托管 | 任务与结果链接有保留期限 | 完成后下载/转存 |
客户端超时如何设置
将提交超时、单次查询超时、总等待时间分别设置。完整示例默认提交 60 秒、单次查询 30 秒、总等待 30 分钟，这些只是客户端选择，不是平台 SLA，也不是生成时长承诺。
总等待到期后提示“已停止等待，可用任务 ID 继续查询”。不要声称生成已取消或一定未计费。已经保存的任务 ID 应持久化到数据库或任务队列中，而不仅放在浏览器内存里。
重试与并发
为业务请求生成自己的唯一 ID，并在本地数据库记录提交状态。只对尚未发出的任务安排发送；若 POST 的发送结果未知，将其标为待核查，避免 SDK、代理或作业系统自动重放。
从小并发开始，根据实际响应与 429 调整。平台没有在本手册承诺固定并发值或“无限并发”。轮询按响应建议间隔执行，加少量随机抖动可以减少同时唤醒。
结果与凭证
- 验证返回 URL 使用 HTTP/HTTPS；下载结果时不要附带 API Key。图片直链应按有访问能力的临时链接保护。
- 查询任务时使用固定本站 origin 与经过编码的 task_id，或严格校验 poll_url 同源，防止 Key 被转发到外域。
- 校验下载 HTTP 状态、Content-Type、大小和图像能否解码。文件扩展名不代表实际格式。
- 将图片转存到你自己的存储，记录模型、参数、任务、结果哈希和实际像素，便于复现与售后。
接入另一套网关或工具
普通 OpenAI Images 客户端通常期待同步 data[]。本站 /async 的任务对象需要下游实现“提交 + 查询 + 终态 + 结果”的完整流程，不是改 Base URL 就自动拥有异步能力。
下游 NewAPI、Sub2API、工作流或插件若不能处理任务对象，使用同步模式并配置足够的连接超时；同时关闭会重放生成请求的自动重试。分组、账务与模型别名也需要下游单独配置。