图片 API 报错排查大全：GPT Image、Gemini、Qwen 指南

图片 API 报错并不是一种问题。 先判断故障发生在鉴权、模型权限、请求参数、配额、安全审核、上游容量、客户端超时，还是响应解析。改代码之前保存完整错误正文，再根据模型和症状进入对应的专项排查文章。

本文面向接入图片生成、图片编辑 API 的开发者。先在这里完成大类判断，再进入对应文章处理具体报错原文、SDK 问题和模型实测。

图片 API 报错后先保存这些信息

把下面字段放进一份脱敏的故障记录：

时间和时区：
服务域名与接口：
完整模型 ID：
HTTP 状态码：
错误 code、message、param：
request ID 与重试响应头：
SDK 与版本：
生成还是编辑请求：
纯文本还是包含参考图：
尺寸、质量、格式、背景设置：
请求耗时：
最小请求能否复现：是/否

对外分享前删除 API Key、签名图片 URL、私密提示词和原始图片。只有最后一行报错的截图通常不够：同一个 400、404 或 429 可能对应几种完全不同的原因。

先按故障层分类

状态码只能缩小范围，错误正文才能决定分支。OpenAI 明确建议对计费类错误继续读取 error.code。Google Gemini 的不同 API 入口使用不同错误结构，解释字段前要先确认实际调用的接口。

GPT Image 报错：先确认模型和 API 入口

先写清楚请求走的是直接 Images API，还是 Responses API 里的图片生成工具。二者能力相关，但请求正文并不能直接互换。参数应与当前 OpenAI 图片生成文档逐项对照。

model_not_found 或没有访问权限

遇到 model_not_found，同时核对完整模型字符串、请求域名、接口和 Key 所属项目。文章或模型目录里出现某个型号，不代表当前项目能通过所有接口调用它。

GPT Image 2.5 使用具体变体名称，不能把家族名当作可调用 ID。生成、编辑和权限检查见 GPT Image 2.5 API 教程；Node.js 包版本、类型定义与运行时错误见 Node SDK 报错指南。

尺寸、画质、格式或透明背景不支持

不要把一个模型的参数原封不动复制到另一个模型。应按精确型号核对 size、quality、background 和 output_format。尺寸被拒绝时看 GPT Image 2.5 尺寸指南；PNG 不透明、出现棋盘格或背景参数报错时，看透明背景排查。

OpenAI 当前文档要求透明输出使用 png 或 webp；jpeg 无法保存透明通道。请求成功后仍要检查原始文件，PNG 扩展名本身不能证明背景透明。

请求很慢、安全拦截或网关超时

客户端超时和上游模型报错是两类问题。记录实际耗时和错误由哪一层返回，再使用 GPT Image 2 失败原因指南区分长耗时、安全审核、封装客户端参数错配、限流和账户前置条件。

Gemini / Nano Banana 报错：读取 status 和配额详情

Gemini 的响应可能同时包含 HTTP 状态、gRPC 风格的 status 和 details 数组，这三部分都应该保留。Google 的 GenerateContent 错误表区分了：

• 400 INVALID_ARGUMENT：请求格式错误，或 API 版本与功能不匹配；
• 402 RESOURCE_EXHAUSTED：预付余额耗尽；
• 403 PERMISSION_DENIED：Key 没有权限；
• 404 NOT_FOUND：模型或引用的媒体资源不存在；
• 429 RESOURCE_EXHAUSTED：请求、Token、图片、日配额或消费限额；
• 503 UNAVAILABLE：临时容量不足；
• 504 DEADLINE_EXCEEDED：在截止时间前未完成。

Gemini 较新的 Interactions API 使用另一份错误参考。该入口定义了 rate_limit_exceeded 等小写错误代码，以及 image_safety、image_prohibited_content、image_recitation 等生成拦截原因，还有无法生成图片时的 no_image。不要假定 GenerateContent 响应也会出现这些字段。无论使用哪个入口，都应保存具体原因、检查对应输入，不能让同一个被拦截请求无限循环。

遇到 429 时，要找到错误里指明的配额指标，并确认 API Key 实际属于哪个项目。Google 文档列出的限制维度包括每分钟请求、每分钟输入 Token、每日请求，以及图片模型的每分钟图片数。如果错误显示免费层配额为零，按 Gemini 图片 API 429 排查核对项目与配额；无限重试不会把零变成正数。

Google 的排错文档建议对临时 429、408 和 5xx 采用指数退避、随机抖动和最大尝试次数。请求格式错误、无效 Key 或余额耗尽不能套用同一策略。

Qwen Image 报错：200 也可能没有完成任务

Qwen Image 接入有两类故障：明确的 API 错误，以及 HTTP 成功但结果不符合代码假设。

Ofox 已记录的 Qwen Image 3.0 Pro 路由测试出现过以下情况：

完整请求、测试日期和限制见 Qwen Image 3.0 Pro 接入实测。这些结论是特定日期、特定路由的记录，不能当作所有阿里云或聚合接口的永久规格。

Grok Imagine 报错：检查别名和迁移

图片模型别名被停用或重新映射后，HTTP 请求可能仍然合法，但输出行为已经变化。把 model ID 放在配置中，记录实际服务每个结果的模型，并将旧别名与服务商的当前迁移说明对照。

当前请求结构可参考 Grok Imagine 图片 API 教程；如果应用仍在使用旧的 quality 别名，应按 Grok Imagine 型号迁移指南处理，不要把迁移导致的变化误判为提示词失效。

Seedream、FLUX 等其他图片模型

不要把 GPT Image 的全部字段强行发送给每个图片模型。即使聚合接口兼容 OpenAI SDK，不同模型的服务商前缀、编辑接口、参考图字段、异步任务方式和输出结构仍可能不同。

暂无专项报错文章的型号，可以按下面顺序排查：

1. 只发送服务商或网关文档里的最小请求。
2. 使用当前精确 model ID，删除所有可选参数。
3. 确认返回的是 URL、base64，还是异步任务 ID。
4. 每次只增加一种能力：尺寸、画质、参考图、编辑、透明背景。
5. 检查实际文件和主体是否符合要求，不能只看 HTTP 200。
6. 联系技术支持前，保存脱敏后的请求和完整响应。

FLUX 2 Max 开发者指南和 Ofox 图片 API 文档可作为最小请求起点。一个模型成功的示例，对另一个模型仍然只是起点。

哪些图片 API 报错应该重试

自己增加重试循环之前，先确认 SDK 是否已经重试该状态。连接中断或超时还可能出现“服务端已完成、客户端没收到”的情况：如果接口返回任务 ID，应先查询原任务，再决定是否新建。保留 request ID 便于支持排查；只有当具体接口明确支持幂等机制时才使用对应参数，否则自动重试可能生成重复图片或创建第二个计费任务。

如果需要跨服务商的 HTTP 层参考，可继续查看 429 是否应该重试。本文保留图片模型特有的能力检查、透明通道和输出验收。

相关图片 API 排错文章

从完整报错原文开始，确定大类后再进入具体模型页面。这样能避免三种常见误操作：请求正文写错却不断更换 Key、零配额下无限重试，以及解析器丢掉有效图片却误以为模型失败。

参考资料

• OpenAI API 错误代码
• OpenAI 图片生成文档
• Google Gemini GenerateContent API 错误
• Google Gemini API 错误参考
• Google Gemini API 排错指南