🍌 Nano Banana
对照错误码和返回信息，排查 Nano Banana 的模型、尺寸、参考图和取图问题。
Top 10 最常见的报错信息
根据数据统计，按 🍌 Nano Banana 失败记录中的占比倒序排列。下方引用的是常见用户可见信息，同一错误码也可能对应其他提示。
请求使用的模型名不正确
22.8%Studio INVALID_ARGUMENT · HTTP 400
Unsupported Gemini image model: nano-banana-pro
Nano Banana 是产品名，不是请求里的模型名。Nano Banana Pro 使用 gemini-3-pro-image，Nano Banana 2 使用 gemini-3.1-flash-image；Studio 统一协议需要加供应商 google/ 前缀。
生图服务暂时不可用
22.0%Studio 502 · type: INTERNAL；Gemini Native 502 / UNAVAILABLE
Upstream service temporarily unavailable
稍后再试。已有 Studio 任务时，先查询其最终状态；大面积故障和恢复会在通知。
图片尺寸不受支持
18.9%Studio 400 · HTTP 500；Gemini Native 500 / INTERNAL
Unsupported image size. Supported image sizes: 512px, 1K, 2K, 4K.
Studio 使用 resolution: "1K"、"2K" 或 "4K"；Gemini Native 使用 generationConfig.imageConfig.imageSize。枚举值大小写要正确，具体可用尺寸以所选模型为准。
余额不足
15.0%Studio 403；Gemini Native 403 / PERMISSION_DENIED
Insufficient account balance
请充值后再提交。PERMISSION_DENIED 也可能有其他原因，只有信息明确提示余额不足时，才按欠费处理。
内容或参数未通过检查
4.7%Studio 422 · HTTP 500；Gemini Native 500 / INTERNAL
The request may have been blocked due to copyright protection. Invalid request parameters or prompt. Please check your request parameters or revise the prompt, then try again.
未通过 Google 的版权保护审核，请检查参数，调整提示词和参考图，避免反复提交相同内容。
Studio 使用了另一套尺寸字段
3.9%Studio invalid_value · HTTP 400
size is not supported for Gemini Studio requests
删除 size，改用 resolution 和 aspect_ratio。
Key 分组不匹配
3.1%Gemini Native 400 / INVALID_ARGUMENT
API key group platform is not gemini
换用 🍌 Nano Banana 分组的 Key；🎨 GPT Image 分组的 API Key 不能用于 Google 生图请求。
模型暂时不可用
2.4%Studio model_temporarily_unavailable · HTTP 500；Gemini Native 500 / INTERNAL
The model is temporarily unavailable.
稍后再试，或主动选择其他可用的模型、分组。持续不可用时请补号。
无法读取 Key 身份与并发额度
2.4%Gemini Native 502 / UNAVAILABLE
Unable to resolve image request identity and concurrency
生图资源限流
1.6%Gemini Native 429 / RESOURCE_EXHAUSTED
Upstream rate limit exceeded, please retry later
等待后再提交，避免密集重试。提示并发超限时，减少同时运行的任务；急用可主动切换其他可用分组。
Reference：静态错误
这些错误来自当前服务的请求校验、任务或图片处理逻辑。
认证、模型与参数
| Studio 错误码 / 原生状态 | 常见返回信息 | 处理 |
|---|---|---|
missing_bearer_token | Missing bearer token | Studio 发送完整的 Bearer 认证头。 |
invalid_bearer_token | Invalid bearer token | 换用有效的 🍌 Nano Banana 分组 Key。 |
原生 401 / UNAUTHENTICATED | API key is required / API key is invalid | 按 Gemini 协议示例提供有效 Key。 |
missing_credential | API key is required | 提供 Key。 |
identity_resolution_failed / 原生 502 / UNAVAILABLE | Unable to resolve image request identity and concurrency | |
invalid_model | model must use openai/<model> or google/<model> | Studio 使用 google/gemini-3.1-flash-image 或 google/gemini-3-pro-image。 |
INVALID_ARGUMENT / 原生 400 / INVALID_ARGUMENT | Unsupported Gemini image model: … | 使用完整的 Gemini 模型名，不使用 nano-banana-pro 这类产品名。 |
invalid_value | size is not supported for Gemini Studio requests | 删除 size，用 resolution 和 aspect_ratio。 |
invalid_value | prompt must be a non-empty string / resolution must be a string / aspect_ratio must be a string | 按 param 检查值和类型。 |
invalid_content_type | Studio image submissions require application/json | Studio 提交 JSON，设置对应 Content-Type。 |
invalid_json / 原生 400 / INVALID_ARGUMENT | Request body is not valid JSON / Request JSON body must be an object | 检查 JSON，发送对象而不是数组或字符串。 |
request_too_large / 原生 413 / INVALID_ARGUMENT | Request body is too large | 请求体过大，将请求体进行缩减，具体上限以实际为准。 |
原生 400 / INVALID_ARGUMENT | Unsupported Gemini image action: … | 使用 generateContent 或 streamGenerateContent 的规范 POST 路径。 |
原生 404 / NOT_FOUND | Unsupported Gemini Files endpoint: … | 使用文档支持的图片输入和媒体接口，不调用 Files 上传接口。 |
method_not_allowed | Method Not Allowed | 按协议页使用正确的 HTTP 方法。 |
not_found / 原生 404 / NOT_FOUND | Resource not found / Job not found / Media was not found | 核对路径与 jobId；Studio 查询使用提交时的 Key。 |
参考图
| Studio 错误码 / 原生状态 | 常见返回信息 | 处理 |
|---|---|---|
edit_image_required | At least one image is required for edits | Studio 编辑通过公共 images 提供至少一张参考图。 |
invalid_value / 原生 400 / INVALID_ARGUMENT | image Data URL is invalid | Studio 的 dataUrl 使用完整 Data URL；Gemini inlineData.data 使用裸 Base64。 |
invalid_image / 原生 400 / INVALID_ARGUMENT | image is empty / image input could not be resolved | 检查图片能否打开；不要传网页或空文件。 |
image_too_large / 原生 400 / INVALID_ARGUMENT | image exceeds maximum allowed size | 单张输入图片过大，具体上限以实际为准。 |
invalid_image_url / 原生 400 / INVALID_ARGUMENT | image URL is not allowed | 使用公网可直接下载的 HTTPS 图片地址。 |
image_download_failed / 原生 400 / INVALID_ARGUMENT | image URL could not be downloaded | 检查地址有效期和访问权限，或改用 Base64 图片输入。 |
幂等、任务与结果
| Studio 错误码 / 原生状态 | 常见返回信息 | 处理 |
|---|---|---|
invalid_idempotency_key / 原生 400 / INVALID_ARGUMENT | Idempotency-Key must be 1-255 visible ASCII bytes | 使用 1 至 255 个可见 ASCII 字符，例如 UUID。 |
idempotency_key_conflict / 原生 409 / ALREADY_EXISTS | Idempotency-Key is already bound to a different request | 找回原任务保持请求一致；新任务换新幂等值。 |
原生 400 / INVALID_ARGUMENT | Idempotency-Key is not supported for streaming requests | streamGenerateContent 不带幂等键；需要幂等恢复时用非流式或 Studio。 |
job_not_finished | Job is not finished | 等任务 completed 后再取结果。 |
cancelled | Job was cancelled / Image generation was cancelled | 停止轮询；仍需要图片时，主动创建新任务。 |
result_expired / 原生 410 / NOT_FOUND | Result has expired / Media has expired | 结果已清理，原链接无法恢复。以后请及时下载。 |
media_unavailable / 原生 500 / INTERNAL | Result media is unavailable / Media is unavailable | |
submission_failed | Failed to submit image request | 提交结果可能不明确；带过幂等键时，使用原 Key、相同幂等值和相同请求找回任务。 |
generation_interrupted | Image generation was interrupted | |
generation_error / 原生 500 / INTERNAL | Image generation failed | |
internal_error | Internal server error |
Studio 图片与结果保留 72 小时。参见 Studio 统一协议 和 超时、扣费与结果找回。
生成连接与图片交付
| Studio 错误码 / 原生状态 | 常见返回信息 |
|---|---|
upstream_transport_error / 原生 502 / UNAVAILABLE | Upstream image request failed |
upstream_error | Upstream image generation failed |
UNAVAILABLE / 原生 502 / UNAVAILABLE | Upstream Gemini response is not valid JSON / Upstream Gemini response must be a JSON object |
upstream_response_too_large / 原生 502 / UNAVAILABLE | Upstream response is too large |
invalid_upstream_image / 原生 502 / UNAVAILABLE | upstream image base64 is invalid / upstream image could not be located |
upstream_image_too_large / 原生 502 / UNAVAILABLE | upstream image exceeds maximum allowed size |
upstream_image_download_failed / 原生 502 / UNAVAILABLE | upstream image could not be downloaded |
media_delivery_failed / 原生 502 / UNAVAILABLE | upstream image could not be stored |
Reference：动态错误
这些是生图服务实际返回给用户的错误码、类型和提示片段。相同数字错误码可能有不同原因，必须对照信息；Studio 的任务错误码与请求的 HTTP 状态不一定相同。
| 公开错误码 / 状态 | 用户可见信息或提示片段 | 有明确原因时的处理 |
|---|---|---|
Studio 400 / 原生 400 / INVALID_ARGUMENT | API key group platform is not gemini | 换用 🍌 Nano Banana 分组 Key。 |
Studio 400（HTTP 500）/ 原生 500 / INTERNAL | Unsupported image size. Supported image sizes: 512px, 1K, 2K, 4K. | 按模型支持的尺寸设置 resolution 或 imageSize。 |
Studio 403 / 原生 403 / PERMISSION_DENIED | Insufficient account balance | 余额不足？去充值 |
Studio 404 / 原生 404 / NOT_FOUND | Model "gemini-3.1-flash-image" is not supported by any configured account in this group | 核对模型名和 Key 分组。 |
Studio 422（HTTP 500）/ 原生 500 / INTERNAL | The request may have been blocked due to copyright protection. Invalid request parameters or prompt. | 核对参数，调整提示词与参考图。 |
Studio 429 / 原生 429 / RESOURCE_EXHAUSTED | Upstream rate limit exceeded, please retry later | 等待后再提交；明确并发受限时降低并发。 |
Studio 502 · type: INTERNAL / 原生 502 / UNAVAILABLE | Upstream service temporarily unavailable | 稍后再试。 |
Studio model_temporarily_unavailable / 原生 500 / INTERNAL | The model is temporarily unavailable. | 稍后再试或换用其他可用模型。 |
Studio upstream_transport_error / 原生 502 / UNAVAILABLE | Upstream image request failed |