# Nano Banana 报错排查：invalid argument、比例不对、没有返回图片

Source: https://ofox.ai/zh/docs/develop/models/nano-banana/errors

参数取值见 [Nano Banana 文生图与尺寸](https://ofox.ai/zh/docs/develop/models/nano-banana/text-to-image)。

## 先按现象找

**要点**:先确认问题类别：参数错误、比例不符、未返回图片，或请求超时。

| 现象 | 最常见的原因 | 跳转 |
|---|---|---|
| `400 Request contains an invalid argument` | 比例或分辨率不在该模型支持范围内 | [invalid argument](#invalid-argument) |
| 输出比例或分辨率与预期不符 | `imageConfig` 写错位置，或该模型不支持这个取值 | [比例或分辨率不对](#ratio) |
| 响应中未找到图片 | 仅读取了 `parts` 的第一项，或请求被安全策略拦截 | [没有图片](#no-image) |
| `410 model_deprecated` | 用了已下线的 `-preview` 模型 ID | [410](#deprecated) |
| 改图结果与原图无关 | 参考图传参方式有误 | [改图写法](#edit) |
| 超时、504、524 | 客户端或代理的超时设置过短 | [超时](#timeout) |

## 400 Request contains an invalid argument

```json filename="400 Bad Request"
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}
```

该报错不会指明具体参数。实测以下情况均返回此错误：

| 请求 | 原因 | 处理方法 |
|---|---|---|
| `aspectRatio: "5:3"` | 比例不在支持列表里 | 改用支持的比例，见[各模型支持的取值](https://ofox.ai/zh/docs/develop/models/nano-banana/text-to-image#support) |
| Nano Banana 传 `aspectRatio: "1:8"` | 上一代不支持 1:4、4:1、1:8、8:1 | 改用 Nano Banana 2 或 2 Lite |
| 2 Lite 传 `imageSize: "512"` 或 `"2K"` | 2 Lite 仅支持 `1K` | 改为 `1K`，或改用 Nano Banana 2 |
| Pro 传 `imageSize: "512"` | Pro 不支持 512 档 | 改为 `1K` 及以上 |
| 任意模型传 `imageSize: "8K"` | 最高为 `4K` | 改为 `4K` 及以下 |

排查方法：先移除 `imageConfig` 重试；若可正常生成，说明问题出在比例或分辨率，再逐项加回定位。

## 比例或分辨率不符
请先检查输出图片的实际宽高，再对照下表排查：

| 情况 | 处理方法 |
|---|---|
| `imageConfig` 写在请求体顶层，和 `contents` 同级 | 移入 `generationConfig`，见下方正确写法 |
| Pro 需要 `1:4`、`4:1`、`1:8`、`8:1` | Pro 不支持这四种比例，请改用 Nano Banana 2 或 2 Lite |
| Nano Banana（2.5）需要 2K、4K | 2.5 不支持 `imageSize`，请改用 Nano Banana 2 或 Pro |
| 用 OpenAI 兼容接口指定尺寸 | 该接口通过 `aspect_ratio` 指定比例，不支持分辨率参数；需要 2K、4K 时请使用原生接口 |
| 未传入比例 | 比例由模型决定；如需固定比例，请显式传入 `aspectRatio` |

正确写法：

```json
{
  "contents": [{ "parts": [{ "text": "..." }] }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": { "aspectRatio": "9:16", "imageSize": "2K" }
  }
}
```

`imageConfig` / `image_config`、`aspectRatio` / `aspect_ratio` 两种写法均可识别，实测 `image_config: { aspect_ratio: "9:16" }` 正确输出 768×1376。

## 响应中没有图片
| 原因 | 处理方法 |
|---|---|
| 仅读取了 `parts[0]` | 响应可能同时包含文字与图片，图片不一定位于第一项。请遍历 `parts`，查找含 `inlineData` 的项 |
| 请求被安全策略拦截 | 见下方 [安全拦截](#safety) |

在 Cherry Studio、LobeHub 等客户端中使用时，请将其添加为图像生成模型，而非聊天模型。

## 410 model_deprecated

```json filename="410 Gone"
{
  "error": {
    "message": "Model 'google/gemini-3-pro-image-preview' is deprecated and no longer accepts requests; please switch to an active model",
    "type": "model_deprecated",
    "code": 410
  }
}
```

以 `-preview` 结尾的旧 ID 已下线，请改用正式版 ID：

| 已下线 | 替换为 |
|---|---|
| `google/gemini-3-pro-image-preview` | `google/gemini-3-pro-image` |
| `google/gemini-3.1-flash-image-preview` | `google/gemini-3.1-flash-image` |

原生接口路径中的模型 ID 可带 `google/` 前缀，也可省略，实测均可正常调用。

## 改图结果与原图无关
| 写法 | 处理方法 |
|---|---|
| 在 `/v1/images/generations` 传 `input_images` | `input_images` 为 Qwen-Image 专用字段，Gemini 不支持。请改用 `/v1/images/edits` 上传文件，或使用原生接口的 `inlineData` |

确认参考图已被读取：原生接口查看 `usageMetadata.promptTokensDetails` 中是否包含 `IMAGE` 项；OpenAI 兼容接口查看 `usage.input_tokens_details.image_tokens`。实测一张 1024×1024 的参考图计 1,120 个 token。

## 安全拦截
请求被安全策略拦截时，响应中不含图片，原因记录在 `finishReason` 或 `promptFeedback.blockReason` 中。各取值的含义（依据 Google 官方定义）：

| 字段值 | 含义 | 处理方法 |
|---|---|---|
| `finishReason: "IMAGE_SAFETY"` | 生成的图片被判定违规 | 修改提示词；原样重试不会改变结果 |
| `finishReason: "PROHIBITED_CONTENT"` 或 `blockReason: "PROHIBITED_CONTENT"` | 提示词或参考图涉及禁止内容 | 修改提示词或更换参考图 |
| `blockReason: "SAFETY"` | 提示词被安全策略拦截 | 修改提示词 |
| `finishReason: "NO_IMAGE"`、`"IMAGE_OTHER"` | 模型没有生成图片 | 使提示词更加明确，或稍后重试 |

代码中不应假定响应必然包含图片：应先检查 `candidates` 是否存在、`finishReason` 是否为 `STOP`，再读取 `inlineData`。各字段定义见 [Gemini API · FinishReason](https://ai.google.dev/api/generate-content#FinishReason)。

## 超时、504、524
接口为同步调用，实测 1K 约 5 至 20 秒，4K 约 30 秒，高峰期耗时更长。常见的 60 秒默认超时无法覆盖。

- 客户端超时设为 300 秒以上。
- 检查 Nginx、Vercel、Cloudflare 等中间代理的超时设置，其默认值通常仅为 60 至 100 秒。
- 4K 的 PNG 约 16 MB，响应体超过 20 MB，请确认代理不会截断大体积响应。

客户端提前断开时，请求仍会计费。

## 其他报错
| 报错 | 原因 | 处理方法 |
|---|---|---|
| `Invalid JSON payload received. Unknown name "image_size": Cannot find field.` | OpenAI 兼容接口传了 `image_size` | 该接口不支持分辨率参数，请改用原生接口的 `imageSize` |
| `404 model_not_found` | 模型 ID 拼写错误 | 从[模型 ID 列表](https://ofox.ai/zh/docs/develop/models/nano-banana#members)复制 |
| `429` | 请求频率超限 | 降低并发，退避后重试，见[速率限制](https://ofox.ai/zh/docs/develop/guides/rate-limits) |

联系技术支持时，请提供响应中的 `request_id` 及完整报错信息。

## 常见问题

**Nano Banana 报错 Request contains an invalid argument 怎么办？**

该报错不会指明具体参数，通常是比例或分辨率超出了该模型的支持范围。例如 5:3 不是支持的比例；Nano Banana 2 Lite 只有 1K；Pro 没有 512；所有模型最大 4K。可先移除 imageConfig 重试，再逐项加回定位。

**Nano Banana 设置了 aspectRatio 但比例不对怎么办？**

先确认 imageConfig 位于 generationConfig 中，而不是请求体顶层。再确认模型支持该取值：Pro 不支持 1:4、4:1、1:8、8:1；上一代 Nano Banana 不支持 imageSize。

**Nano Banana 响应里找不到图片是什么原因？**

常见原因是代码仅读取了 parts 的第一项，而图片位于其后；请遍历 parts 查找 inlineData。另一原因是请求被安全策略拦截，此时 finishReason 不是 STOP。

**gemini-3-pro-image-preview 报 410 model_deprecated 怎么办？**

预览版 ID 已下线。把 google/gemini-3-pro-image-preview 替换为 google/gemini-3-pro-image，把 google/gemini-3.1-flash-image-preview 替换为 google/gemini-3.1-flash-image。

**Nano Banana 出现 IMAGE_SAFETY 怎么办？**

IMAGE_SAFETY 表示生成的图片被安全策略判定违规，原样重试结果不变。修改提示词，避免真实人物、受版权保护的角色或敏感内容后再试。

**Nano Banana 改图时参考图没有生效？**

input_images 是 Qwen-Image 的字段，Gemini 不支持。改用 /v1/images/edits 上传文件，或在 Gemini 原生接口中将图片作为 inlineData 和文字放入同一个 parts。