🎨 GPT Image

对照错误码和返回信息，排查 GPT Image 的生成、编辑与取图问题。

Top 10 最常见的报错信息

根据数据统计，按 🎨 GPT Image 失败记录中的占比倒序排列。下方引用的是常见用户可见信息，同一错误码也可能对应其他提示。

1route.dev 站内余额不足

INSUFFICIENT_BALANCE / billing_error / upstream_error · HTTP 403

解决方案：

账户余额不足，请充值后再提交。

余额不足？去充值

请求未携带 API Key

missing_bearer_token · HTTP 401

解决方案：

请求头添加 Authorization: Bearer YOUR_API_KEY。工具中填写 Key 后，确认它会将认证头发送到生图接口。

没有 Key？去创建创建时选择 🎨 GPT Image 分组。

内容审核/撞甲

type: invalid_request_error · HTTP 400

举例：

您的请求无法用于生成图像。该请求可能因安全政策被拦截，或不适合进行图像生成。

解决方案：

先检查返回信息和参数。出现这类安全提示时，调整提示词、参考图后再提交，不要原样连续重试。参见 400 与内容审核。

接口路径或调用方式不对

unsupported_images_endpoint · HTTP 404

举例：

Unsupported images endpoint: /v1/images/edits

解决方案：

核对 Base URL、路径和请求方法。按 OpenAI Images 示例使用 POST /v1/images/generations 或 POST /v1/images/edits；不要重复拼接 /v1。

Key 无效

invalid_api_key · HTTP 401

举例：

Invalid API key

解决方案：

检查是否漏复制、带了多余空格，或 Key 已失效。换用有效的 🎨 GPT Image 分组 Key。

没有 Key？去创建创建时选择 🎨 GPT Image 分组。

当前分组不支持这个模型

model_not_found / upstream_error · type: model_not_found · HTTP 404

举例：

Model "gpt-image-2" is not supported by any configured account in this group

解决方案：

从模型对比复制准确的模型名，并使用支持该模型的分组 Key。Studio 模型名加 openai/ 前缀，OpenAI Images 不加。

生成连接失败

upstream_transport_error · HTTP 502

举例：

Upstream image request failed

解决方案：

遇到这种情况，若非出现大面积生图故障，那么一般是请求打到了限流账号；重试即可。或减少参考图的数量再试。

参数格式不正确

invalid_value · HTTP 400

举例：

size must be auto, 1K, 2K, 4K, or WIDTHxHEIGHT

解决方案：

按错误中的 param 修改对应字段。出现这条尺寸提示时，使用 auto、1K、2K、4K 或 1024x1024 这样的格式；不要填写 1024*1024。

生图服务暂时不可用

upstream_error · HTTP 502

举例：

Upstream service temporarily unavailable

解决方案：

稍后再试。已有 Studio 任务时，先查询原任务是否已经结束；大面积故障和恢复会在通知。

当前分组暂无可用资源

upstream_error · type: api_error · HTTP 503

举例：

No available compatible accounts

解决方案：

检查模型名是否正确、使用的分组是否是特殊分组（官Key、渠道等）。特殊分组可能偶尔不稳定，可在。

Reference：静态错误

这些错误由当前服务的请求校验、任务或图片处理逻辑产生。

认证与请求

错误码	常见返回信息	处理
`missing_bearer_token`	Missing bearer token	添加完整的 Bearer 认证头。
`invalid_api_key` / `invalid_bearer_token`	Invalid API key / Invalid bearer token	检查并更换有效 Key。
`missing_credential`	API key is required	在请求中提供 Key。
`identity_resolution_failed`	Unable to resolve image request identity and concurrency
`invalid_model`	model must use openai/<model> or google/<model>	Studio 的 GPT Image 模型使用 `openai/` 前缀。
`invalid_content_type`	Studio image submissions require application/json	Studio 提交 JSON，设置 `Content-Type: application/json`。
`invalid_json`	Request body is not valid JSON / Request body must be an object	发送合法 JSON 对象，检查逗号、引号和请求体。
`invalid_multipart`	Multipart body is invalid	文件编辑使用客户端的 multipart 构造器，不要手写 boundary。
`invalid_request`	Only one mask is supported / Request JSON body must be an object / Invalid image Data URL	检查遮罩数量、JSON 对象和图片编码，按具体提示修改。
`invalid_value`	prompt must be a non-empty string / size must be auto, 1K, 2K, 4K, or WIDTHxHEIGHT	按 `param` 修正字段；Studio 的 GPT Image 使用 `size`，不发送 `resolution`、`aspect_ratio`。
`request_too_large`	Request body is too large	缩减请求体。
`unsupported_images_endpoint`	Unsupported images endpoint: …	核对 Images 路径与请求方法。
`unsupported_action` / `unsupported_protocol`	Unsupported OpenAI Images action: … / Unsupported OpenAI protocol route	使用文档中的 Images 接口。
`method_not_allowed`	Method Not Allowed	生成与编辑使用 POST，查询按文档使用 GET。
`not_found`	Resource not found / Job not found / Media was not found	检查路径；查询任务时使用提交时的 Key 和准确的 `jobId`。

参考图与遮罩

错误码	常见返回信息	处理
`edit_image_required`	At least one image is required for edits	编辑请求至少提供一张参考图。
`edit_too_many_images`	Image edits support at most 16 input images	减少参考图数量，具体上限以实际为准。
`edit_too_many_masks`	Image edits support at most one mask	只保留一张遮罩。
`edit_unsupported_image_type`	image is not a supported image	使用有效的 PNG、JPEG 或 WebP 图片。
`edit_unsupported_mask_type`	mask is not a supported image	使用带透明区域的 PNG 遮罩。
`edit_image_too_large`	image exceeds maximum allowed size	OpenAI 编辑输入图过大，具体上限以实际为准。
`edit_mask_too_large`	mask exceeds maximum allowed size	遮罩图片过大，具体上限以实际为准。
`edit_mask_dimensions_mismatch`	mask dimensions must match the first input image	遮罩宽高与第一张参考图完全一致。
`invalid_image`	image is empty / image input could not be resolved	确认文件能正常打开，URL 返回的是图片而非网页。
`invalid_value`	image Data URL is invalid	检查 Base64 编码；Data URL 需要完整的 `data:image/png;base64,...` 格式。
`image_too_large`	image exceeds maximum allowed size	缩减图片输入的大小。
`invalid_image_url`	image URL is not allowed	使用可公开下载的 HTTPS 图片地址，不使用本机、内网或登录后才能访问的地址。
`image_download_failed`	image URL could not be downloaded	检查链接有效期和可访问性，或改用文件 / Data URL。
`unsupported_file_id`	images[0].file_id is not supported / mask.file_id is not supported	改用图片文件、公开 URL 或 Data URL。

幂等、任务与结果

错误码	常见返回信息	处理
`invalid_idempotency_key`	Idempotency-Key must be 1-255 visible ASCII bytes	使用 1 至 255 个可见 ASCII 字符，例如 UUID。
`idempotency_key_conflict`	Idempotency-Key is already bound to a different request	找回旧任务时保持请求一致；新任务使用新的幂等值。
`idempotency_not_supported_for_streaming`	Idempotency-Key is not supported for streaming requests	原生流式请求不带幂等键；需要幂等恢复时使用非流式或 Studio。
`job_not_finished`	Job is not finished	继续查询状态，等 `completed` 后再取结果。
`cancelled`	Job was cancelled / Image generation was cancelled	停止查询；仍需要图片时，主动创建新任务。
`result_expired`	Result has expired / Media has expired	结果已清理，无法从原链接找回；以后请在保留期内下载。
`media_unavailable`	Result media is unavailable / Media is unavailable
`submission_failed`	Failed to submit image request	提交结果可能不明确；带过幂等键时，用相同 Key、幂等值和请求找回。
`generation_interrupted`	Image generation was interrupted
`generation_error`	Image generation failed
`internal_error`	Internal server error

图片和结果保留 72 小时。取图失败不一定意味着生图失败，详见扣费与结果找回。

生成连接与图片交付

错误码	常见返回信息
`upstream_transport_error`	Upstream image request failed
`upstream_error`	Upstream image generation failed
`upstream_invalid_response`	Upstream OpenAI Images response is not valid JSON / Upstream stream image payload is invalid
`upstream_response_too_large`	Upstream response is too large
`invalid_upstream_image`	upstream image base64 is invalid / upstream image could not be located
`upstream_image_too_large`	upstream image exceeds maximum allowed size
`upstream_image_download_failed`	upstream image could not be downloaded
`media_delivery_failed`	upstream image could not be stored

Reference：动态错误

这些是生图服务实际返回给用户的错误码、类型和提示片段。同一个 upstream_error 可能是余额、模型、限流或服务错误，必须结合 type 和 message 判断。

错误码 / 类型	用户可见信息或提示片段	有明确原因时的处理
`INSUFFICIENT_BALANCE` / `billing_error`	Insufficient account balance / insufficient balance	余额不足？去充值
`API_KEY_QUOTA_EXHAUSTED`	API key 额度已用完	检查 Key 自身的额度限制；账户有余额也可能触及此限制。
`400` / `invalid_request_error`	您的请求无法用于生成图像。该请求可能因安全政策被拦截，或不适合进行图像生成。	调整提示词和参考图，同时核对参数。
`429`	No available image quota. Please try again later.	等待资源恢复；这条提示不等同于账户余额不足。
`ContentModerationRejected`	提示词或参考图未通过内容审核，请修改后重试	修改提示词或参考图，避免重复违规。
`moderation_blocked`	Your request was rejected by the safety system.	调整内容，遵守内容政策。
`content_moderation`	Request rejected by upstream validation. Please check your prompt, parameters and input media, then try again.	检查提示词、参数与参考图。
`ERR-*` · `content_policy_error` / `invalid_request_error`	带 `ERR-` 前缀的公开错误参考码，提示内容随错误变化	以返回的公开信息为准；内容政策提示先调整内容。
`API_PARAM_VALIDATION_FAILED` / `invalid_value`	Invalid size '3072x4096'. The longest edge must be less than or equal to 3840.	模型生图尺寸最大大小有限制。具体上限以实际请求模型为准。
`invalid_value` · `image_generation_user_error`	参数或图片输入不符合当前模型要求	按返回信息修正对应字段。
`InvalidInput`	提示词或嵌入内容无效或过长，请仅保留本次生成指令并移除历史对话后重试。	缩短提示词，移除不必要的历史对话。
`InvalidRequest`	At least one uploaded image is required	文件编辑请求附上参考图；核对客户端实际发送的 multipart。
`GenerationRequestFailed`	生成请求失败，请检查参数后重试	核对协议页的参数和请求格式。
`invalid_request_error`	images endpoint requires an image model, got "gpt-image"	使用文档中完整、准确的模型名。
`service_error`	/v1/images/edits requires multipart/form-data	需要上传文件的调用按 multipart 示例构造。
`model_disabled`	The model 'gpt-image-2.5-flare' is currently disabled. Please use another available model.	换用当前可用的模型。
`model_not_found`	Model "gpt-image-2" is not supported by any configured account in this group	检查模型名及 Key 分组。
`model_temporarily_unavailable`	The model is temporarily unavailable.	稍后再试或选择其他可用模型。
`not_found_error`	Images API is not supported for this platform	使用支持 Images 的分组 Key 和对应协议。
`permission_error`	Image generation is not enabled for this group	换用已开启生图的分组 Key。
`rate_limit_error`	Upstream rate limit exceeded, please retry later	等待后再提交；并发受限时减少同时进行的任务。
`api_error`	No available compatible accounts	稍后再试，或主动切换可用分组。
`upstream_error`	Insufficient account balance / Upstream service temporarily unavailable / No available compatible accounts	结合完整公开提示，分别按余额、服务不可用或资源暂缺处理。

generation_interrupted、invalid_upstream_image、upstream_image_download_failed、upstream_transport_error 也出现在实际失败记录中，其固定公开含义见上面的静态索引。

Top 10 最常见的报错信息

Reference：静态错误

认证与请求

参考图与遮罩

幂等、任务与结果

生成连接与图片交付

Reference：动态错误

本页内容