先保留哪些信息
保存HTTP状态、模型ID、调用时间、脱敏响应及响应中实际出现的请求标识。不要记录API Key、完整Base64私人图片或带访问凭据的素材链接。错误代码可能随请求链路不同而变化，优先阅读 error.code 与 error.message。
排查表
| 现象 | 排查与处理 |
|---|---|
| 401或鉴权失败 | 请求头使用 Authorization: Bearer YOUR_API_KEY，替换为有效的青云TOP API Key；检查空格、过期、停用状态。不要使用厂商Key。 |
| 403、模型无权限或不可用 | 核对完整模型ID、API Key模型权限、分组和额度。5.0 Lite使用 doubao-seedream-5-0-260128；不要将Pro或官方别名直接代入。 |
| 404或路径错误 | 本目录使用 /v1/images/generations；图片编辑也走此路径，不使用 /api/v3 或 /v1/images/edits。 |
| 400、尺寸不合法 | 同时检查像素乘积和宽高比。5.0 Lite/4.5不接受1024x1024；可先用2K。宽高字符串使用小写ASCII x。 |
| output_format报错 | 仅5.0 Lite设置png/jpeg；4.5、4.0省略。PNG输出不代表可以设置透明背景。 |
| 参考图片无法读取 | 确认URL直接返回图片、无需登录且未过期；不要使用内网地址、本地路径或网页分享链接。 |
| Base64或素材格式错误 | 使用小写的 data:image/png;base64, 等正确前缀，编码真实文件；逐张核对30MB、像素、比例和格式限制。 |
| 413或请求体过大 | 压缩或缩小素材，减少参考图，必要时换成稳定公网URL。Base64会增加请求体积。 |
| 参考图顺序混乱 | image 使用有序字符串数组，提示词中的图1/图2对应数组索引0/1。最多14张参考图，输出按单图使用。 |
| 组图、联网或优化参数没有预期效果 | 本目录未提供这些参数组合的调用保证。移除额外参数，按单图示例接入；需要高级能力时先联系支持确认入口。 |
| 内容拒绝或图片项返回error | 阅读具体错误并调整提示词/素材以满足内容规则；不要用循环重试绕过拒绝。 |
| 429 | 按响应指示等待，有Retry-After时遵循它；降低并发并采用有限退避，避免批量立即重试。 |
| 5xx、请求超时或断线 | 先记录结果不确定。请求可能已被处理，不要自动无上限重发；确认状态后再决定是否重新生成。 |
| 流式HTTP 200但没有图片 | 检查SSE的error/partial_failed，按空行解析事件；完成汇总通常不含图片，图片来自partial_succeeded。缺少图片或完成事件均不能认定完整成功。 |
| 图片下载403/404、空文件或HTML | 可能是链接失效、访问失败或错误页。下载不携带本站Key；核对URL和文件字节，保留生成记录联系支持。 |
旧型号与功能边界
Seedream 3.0、SeedEdit 3.0已进入官方下线或关停流程，旧名称仍出现在某处列表不代表可继续使用。请按模型选择迁移至5.0 Lite、4.5或4.0。
本目录没有单独的任务状态查询、取消或webhook接口。客户端停止等待不能保证服务端取消；不要猜测任务ID或套用视频模型的查询路径。