按错误定位问题
| 现象 | 排查与处理 |
|---|---|
| 401 / invalid API key | 使用青云TOP API 的 API Key，检查 Authorization、Bearer 后的空格和 Key 是否有效；不要使用文档站登录凭据 |
| 403 / 无模型权限 | 检查 Key 分组、模型范围和账户权限；目录列出模型不代表每个分组都可调用 |
| 404 / 找不到接口 | 基础地址使用 top.qingyuntop.ai，检查是否重复拼接 /v1；生成与编辑分别使用 images/generations 与 images/edits |
| 模型不存在或无可用入口 | 使用完整模型 ID；2.5 必须带 sunburst 或 flare，不盲目添加日期或 -c 后缀 |
| 400 / quality 无效 | 2.5 可用 xhigh/max，2、1.5、1 使用 auto/low/medium/high；删除 hd/standard |
| 400 / size 无效 | 使用半角 x；2/2.5 的自定义宽高必须是 16 的倍数，比例在 1:3–3:1，且满足模型像素及边长限制 |
| 缺少 image / images | multipart 上传二进制 image 或重复 image[]；JSON 使用 images 对象数组，内含 image_url |
| 素材无法获取 | 检查 URL 是图片本身、无需登录且未过期；可改用 Data URL 或本地文件上传 |
| 蒙版无效 | PNG、小于 4 MB、含 alpha、尺寸与首图相同；透明区域是编辑区域 |
| 413 / 请求过大 | 检查单图、总请求和 Base64 体积；压缩素材、减少输入图，或使用文件上传 |
| 429 / 限流或额度相关错误 | 阅读错误正文，检查余额和并发；按 Retry-After（若有）及指数退避加随机抖动重试，设置最大重试次数 |
| 5xx / 生成途中连接关闭 | 保留请求时间、模型和脱敏错误，先核对控制台记录；不要无上限自动重试 |
| HTTP 200 但流中出现 error | 将流内错误作为失败信号处理，检查是否已收到部分最终图片；不要只看 HTTP 状态 |
| 文件打不开 | response.json 不是图片；Base64 需解码，文件后缀应匹配 output_format |
HTTP 状态用于初步判断，具体原因以响应中的 error.message、error.type 和 error.code（若存在）为准。不要在支持请求中提供 API Key、Authorization 请求头或含敏感图片的完整请求体。
从 GPT Image 1 / 1.5 迁移
生成接口和编辑接口路径不变。将 model 改为 gpt-image-2、gpt-image-2.5-sunburst 或 gpt-image-2.5-flare，先保留标准尺寸、n=1、quality=medium 和 PNG，用已有提示词检查效果，再逐步调整质量与尺寸。
2.5 的两个模型可以使用 xhigh 和 max；回退到 2、1.5 或 1 时同步回退档位。2 支持自定义尺寸，但透明背景处于预览阶段。不要只替换 model 后沿用所有高档位、实验尺寸或旧响应假设。
| 旧写法或误区 | 当前写法 |
|---|---|
| format=jpeg | 使用 output_format=jpeg |
| response_format=url 或 b64_json | GPT Image 省略该参数，读取 data[].b64_json |
| 文档标题是 1.5，body 仍是 gpt-image-1 | 明确填写要调用的模型 ID，检查实际发送的请求 |
| 编辑请求只有 prompt/model | 同时上传 image 文件，或提供 JSON images 引用数组 |
| size 用 × 或 * | 使用半角字母 x |
| multipart 手写 Content-Type: application/json | 让客户端生成带 boundary 的文件表单请求头 |
| 把输入图数量写入 n | 素材数量由图片列表决定，n 表示生成图片数 |
| 使用 images/variations 派生图片 | 本目录不提供该流程；带参考图调用 edits |
超时、取消与重复调用
普通 Images 请求和 SSE 都不提供本目录可用的任务查询、取消、列表或删除流程。客户端超时、关闭网页或断开连接不自动取消上游生成，也不构成退款承诺。对于已提交但结果不明确的请求，先检查记录或联系支持再重发。
不使用视频任务 API 来查询图片，也不把 created 时间戳当作任务 ID。如果需要多轮编辑，将上一次保存的图片作为下一次编辑输入，明确描述变化；不要直接把 Images 响应传成 Responses 的 previous_response_id。