# Nano Banana Pro 提示“Unsupported file URI type”？先把 Gemini 文件路径修对

> 遇到 Unsupported file URI type，先检查图片字段实际发出的值：它应是当前接口支持的单一引用，而不是本地路径、未展开表达式或数组。原生 Gemini 已支持符合条件的 HTTPS 图片地址，也可使用原始 base64 或上传返回 URI。

- URL: https://blog.laozhang.ai/zh/posts/nano-banana-pro-unsupported-file-uri-type
- Published: 2026-04-09
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: 故障排查
- Tags: Nano Banana Pro, Gemini API, Files API, image_url, 文件路径

---
Nano Banana Pro 提示 `Unsupported file URI type` 或 `Invalid or unsupported file uri` 时，先检查**请求真正发出的图片字段**，再决定怎么修。`{{ $json.imageUrls }}` 没有展开、一个地址被包装成数组、本地路径放进 `fileUri`，以及原生接口混入兼容接口的字段，都是值得先排除的情况。改提示词不能把这些输入变成有效图片。

如果你发的是正常 HTTPS 图片地址，也不要直接认定“Gemini 不支持 URL”。Google 在 **2026 年 10 月 1 日更新的原生文件输入指南**中，已列出公网 HTTPS 和预签名地址的直接输入方式；是否能用仍取决于模型、接口、可访问性、有效期、媒体类型和大小限制。旧版 Gemini 2.0 的限制不能套到当前所有模型上。[Google 文件输入方式说明](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)

这篇按原生 Gemini `generateContent` 的图片编辑任务说明修复方法。当前官方文档中 Nano Banana Pro 的模型 ID 是 `gemini-3-pro-image`；旧教程里的 preview ID、第三方网关别名及账号实际可用模型需要分别核对。不要为了让请求通过，悄悄换成只描述图片的模型。[Google 图片生成与编辑文档](https://ai.google.dev/gemini-api/docs/image-generation)

## 先看报错里到底是哪一个 URI

最有用的检查位置是 HTTP 请求发送前，完成变量替换和序列化之后。工作流界面显示“已选图片”，并不证明最终字段就是图片地址。

先保留错误原文、请求目标的主机与路径、模型 ID、SDK 或网关版本，再检查失败图片 Part 的字段名和类型。日志只记录诊断所需信息，隐藏 API 密钥、签名 URL 的查询参数及私人图片内容；不要把完整 base64 打出来。

| 实际发送的值或字段 | 应该怎么处理 |
| --- | --- |
| `{{ $json.imageUrls }}` 等表达式原文 | 先让工作流完成变量求值，确认输出为图片值，再发送；把表达式文字换个字段不会解决求值问题 |
| `fileUri: ["https://…"]` 或字符串 `"[\"https://…\"]"` | `fileUri` 要一个字符串。多张图分别放入多个图片 Part，不能把整个数组当作一个 URI |
| `undefined`、空值或字段缺失 | 检查上游字段名与分支是否真的有输出。序列化时 `undefined` 属性可能直接消失，并非总会变成字符串 |
| `/tmp/a.png`、`file:///…`、`content://…` | 由你的程序读取图片字节后内联，或上传到 Files API；不要当作 Google 服务端能读取的本地路径 |
| `data:image/png;base64,…` 放在原生 `fileUri` | 改为 `inlineData`，其中 `data` 只放原始 base64，去掉 data URL 前缀 |
| 一个正常 HTTPS 字符串 | 检查当前接口是否支持直接获取，图片是否可由服务端访问，地址是否仍有效，MIME 与请求限制是否匹配 |
| Files API 返回的 URI | 检查是否使用了返回的 `uri`、资源状态及过期时间，不能用文件名或 `files/…` 资源名称猜一个地址 |

商户曾报告报错中直接出现 `{{ $json.imageUrls }}` 的未展开表达式案例，这能说明该症状值得检查，却不能证明所有同名错误都由它导致，也不能据此承诺修复成功率。[该案例的原始说明](https://help.apiyi.com/en/nano-banana-pro-unsupported-file-uri-type-error-fix-en.html) 原生 `Part` 和 `FileData` 的字段类型以 [Google API 定义](https://ai.google.dev/api/generate-content)为准；不同包装器未必返回相同错误文字。

## 原生 Gemini：HTTPS 可以直接传，字段必须正确

![HTTPS、内联图片、Files 上传及 GCS 注册的输入字段与生命周期示意。](https://blog.laozhang.ai/posts/zh/nano-banana-pro-unsupported-file-uri-type/img/uri-routes.webp)

图片用于识别输入类别；HTTPS 是否可直接传入，以本节当前接口条件为准。

若你的请求目标是 `generativelanguage.googleapis.com/v1beta/models/…:generateContent`，图片引用位于 `contents[].parts[]`。一个 Part 使用一种数据类型：文字和图片分开，图片的 `fileData.fileUri` 是单一字符串。不要在原生 Part 中放 OpenAI 的 `image_url`。

下面是**原生请求体片段**。把示例域名换成你已获准使用、服务端能获取的实际 PNG 图片地址；示例域名不是可直接调用的测试图片：

```json
{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "把这张图片的背景改成浅灰色，保留主体。"},
      {"fileData": {
        "mimeType": "image/png",
        "fileUri": "https://example.com/input.png"
      }}
    ]
  }],
  "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}
```

本文使用 API 定义中的 camelCase JSON 字段。官方部分 REST 示例也使用 snake_case，SDK 则有各自的参数写法；应保持所用序列化器的文档写法一致，不把几套格式拼成一个请求。[原生请求与字段定义](https://ai.google.dev/api/generate-content)

地址格式正确后，再检查获取条件：

- 地址返回的是实际图片，不是登录页、分享页或 HTML 错误页面；浏览器里能打开可能只是因为浏览器已登录。
- 预签名地址在服务端处理时仍有效，授权范围允许读取对应对象；不要删除签名参数来“清理 URL”。
- `mimeType` 与真实图片一致，文件大小符合所用方法、模型和网关限制。
- 若响应明确给出 `URL_RETRIEVAL_STATUS_UNSAFE`，这是获取安全检查的拒绝，应处理被拒绝的输入或改用获准的输入方式，不绕过检查。

当前指南列出外部 URL 每次载荷 100 MB 的通用限制，也明确不同方法、文件和模型存在差异。**这不等于每个 Nano Banana Pro 请求或代理都能接收 100 MB 图片。** 排错时先用一张较小、用途明确的图片，避免同时引入多图、超大文件和短期签名三个变量。[URL 条件与各输入方式限制](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)

## 本地图片：读取字节后内联，不把路径交给服务端

如果图片只在你的设备上，原生请求可以使用 `inlineData`。`mimeType` 描述图片类型，`data` 是图片字节编码后的 base64，**没有** `data:image/png;base64,` 前缀。这条路不要求先上传，也不要求把私人图片放到公开存储中。[Google 原生图片编辑示例](https://ai.google.dev/gemini-api/docs/image-generation)

下面的 Python 程序只生成请求文件，不联网。将它保存为 `make_request.py`，并准备一张你有权使用的 `input.png`：

```python
import base64
import json
from pathlib import Path

image_path = Path("input.png")
image_bytes = image_path.read_bytes()
if not image_bytes.startswith(b"\x89PNG\r\n\x1a\n"):
    raise ValueError("input.png 必须是实际 PNG 图片")

payload = {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "把图片背景改成浅灰色，保留主体。"},
            {"inlineData": {
                "mimeType": "image/png",
                "data": base64.b64encode(image_bytes).decode("ascii")
            }}
        ]
    }],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}
Path("request.json").write_text(
    json.dumps(payload, ensure_ascii=False), encoding="utf-8"
)
```

运行 `python3 make_request.py` 后，确认生成了 `request.json`。若使用 JPEG，需相应调整文件读取、格式判断和 MIME，不能只给 JPEG 改名为 PNG。此处头部检查用于避免明显误传，不代替完整图片解码。

接下来才是实际模型调用。下面命令要求你已在自己的终端设置有效的 `GEMINI_API_KEY`，且有该模型的调用权限；执行会发送图片并可能产生费用。本文示例已做本地构造检查，没有代你执行上传或模型调用。

```bash
curl --fail-with-body --silent --show-error \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json
```

这样保留了原生 `generateContent` 和 Pro 图片编辑任务，仅把无法读取的本地 URI 换成图片字节。若要验证 HTTPS 修复，可将上一节的请求体保存为 `request.json`，仍使用同一模型目标调用；一次只改输入方式，结果才便于比较。

## 复用 Files API 图片时，用返回的 URI 和实际状态

图片需要在多个请求里复用时，可以上传到 Files API，再把**上传结果中的 `uri` 和 MIME**放入原生 `fileData`。不要传本地路径、显示文件名，也不要把 `name` 当作 `uri`。二者是 File 资源的不同字段。[File 资源定义与上传接口](https://ai.google.dev/api/files)

上传后检查资源状态。`ACTIVE` 表示可用于推理；`PROCESSING` 尚未就绪，应按你的任务设置有上限的等待并再次查询；`FAILED` 应读取错误并停止等待。需要查询时，用返回的资源 `name` 调用 `files.get`，而生成请求使用资源 `uri`。这两步不要混用。

标准上传文件保留 48 小时，复用前应检查 `expirationTime` 或获取当前资源状态；已经失效就重新上传并更新缓存 URI。不要把原封不动的失效 URI 反复提交，也不要把这 48 小时套到所有注册资源或第三方图片地址上。[Google 文件输入与生命周期说明](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)

### GCS 文件可以注册，但 API key 本身不够

如果原图在 Google Cloud Storage，原生 Gemini 提供 `files.register`：请求的 `uris[]` 放 GCS 对象路径，返回 `files[]` 后，再将返回 File 的 `uri` 用于生成请求。这里注册接口的数组参数，与生成请求中一个 `fileUri` 字符串是两件事。[注册接口定义](https://ai.google.dev/api/files)

注册需要相应 OAuth 身份、调用方权限，以及 Gemini 服务代理读取目标 bucket 对象的权限；当前指南要求按说明配置服务身份和 bucket 范围的 Storage Object Viewer。**只有 API key，不能据此假定注册已获得权限。** 已有组织存储策略应由负责方核对，不需要为修一个 URI 报错就把 bucket 改成公开。[GCS 注册的认证与权限前提](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)

注册引用不复制文件，一次注册可提供最长 30 天访问，与普通上传 48 小时不同；原对象仍需满足读取条件。若你实际调用 Vertex AI，则应继续按它的项目、地区、认证和对象规则排查，不能只替换主机名。2025 年关于 Gemini 2.0 与 `gs://` 的[论坛讨论](https://discuss.ai.google.dev/t/400-invalid-or-unsupported-file-uri/73951)有其历史背景，不足以否定当前原生 URL 和注册方式。

## OpenAI 兼容接口与网关，不能只看字段像不像

如果你的实际目标是 Gemini 的 `/v1beta/openai/`，官方图片理解示例使用 `content` 中的 `image_url`：

```json
{
  "type": "image_url",
  "image_url": {"url": "data:image/png;base64,<图片的base64>"}
}
```

这是**兼容接口的图片输入片段**，占位内容不能直接运行。这里的 data URL 前缀合法，不表示原生 `fileUri` 也接受它。兼容接口的看图示例还不能证明你所用模型和动作支持 Pro 图片编辑输出；需核对对应生成或编辑接口，而不是把得到文字回答当成修复完成。[Google OpenAI 兼容文档](https://ai.google.dev/gemini-api/docs/openai)

SDK 和网关还可能改变传输方式：你的代码传了 URL，SDK 却先下载成字节；换成网关后，可能直接把 URL 转交上游。所以“直连 SDK 成功”不能单独证明模型服务端曾成功拉取同一个 URL。2025 年的 [Vercel AI 问题报告](https://github.com/vercel/ai/issues/10692)记录过类似差异，但不证明当前版本仍有同一缺陷。排查应比较版本、目标接口和最终图片 Part，不盲目按旧帖降级。

也要把包装器自己的限额分开。例如 Comfy 的 Nano Banana Pro 路线使用 `api.comfy.org` 和其独立密钥，文档中的内联 20 MB 与生成图片签名地址 24 小时属于该包装器；不能拿来解释 Google Files 上传的 48 小时，也不能将 Google 通用 100 MB 限制当成 Comfy 的额度。[Comfy Nano Banana Pro 接口说明](https://docs.comfy.org/ja/development/comfy-router/models/google/nano-banana-pro/code)

## URI 报错消失后，确认确实拿到了编辑图片

![文件输入修复后的图片输出验证与继续排查示意](https://blog.laozhang.ai/posts/zh/nano-banana-pro-unsupported-file-uri-type/img/verify-flow.webp)

成功验证包含两个结果：同一接口不再拒绝图片输入，且同一 Pro 模型返回了符合原任务的编辑图片。HTTP 200、只有文字描述，或者换模型后能识别图片，都不等于完成原来的图片编辑。

对上面原生调用产生的 `response.json`，可用以下本地程序提取非思考图片。保存为 `save_image.py` 后执行 `python3 save_image.py`：

```python
import base64
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8"))
if "error" in response:
    raise RuntimeError("请求失败，请先检查 response.json 中的错误")

images = []
for candidate in response.get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        media = part.get("inlineData", {})
        if not part.get("thought") and media.get("mimeType", "").startswith("image/"):
            if media.get("data"):
                images.append(media)

if not images:
    raise RuntimeError("没有实际图片输出；检查 finishReason 和响应内容")

image = images[-1]
extensions = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}
extension = extensions.get(image["mimeType"])
if extension is None:
    raise ValueError("输出格式需要另行处理，不能直接改名为 PNG")
output = Path("edited" + extension)
output.write_bytes(base64.b64decode(image["data"], validate=True))
print("已保存：", output)
```

这里解析的是原生 REST 的 JSON 响应；SDK 对象或网关返回 URL 时，要按对应响应格式处理。打开保存的图片，检查主体是否保留、背景是否完成要求的修改。若收到多个最终图片，示例只保存最后一个，你的业务应按需要逐一处理。[Google 图片响应与编辑示例](https://ai.google.dev/gemini-api/docs/image-generation)

若仍是 URI 错误，回到实际发送字段，核对模板求值、单一字符串、资源状态和获取条件。若错误已经变成权限、模型不存在、配额或多轮编辑的签名问题，应按**新的错误内容**排查，停止对同一个 URI 做无效替换；尤其不要把当前接口接受了图片，推导成计费、配额和输出内容都已正常。

## 常见追问

### 公网图片 URL 一定要先上传吗？

不一定。当前原生 `generateContent` 支持符合条件的公网 HTTPS 和预签名地址，Gemini 2.0 不支持这条方式；还需核对所用模型与包装器。图片只在本地时，可以读取字节后内联；需要复用时可上传并使用返回 URI。[官方输入方式说明](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)

### `data:image/png;base64,…` 为什么在一处能用，另一处报错？

字段和接口不同。Gemini OpenAI 兼容图片理解示例把 data URL 放在 `image_url.url`；原生 `inlineData.data` 要无前缀的 raw base64，原生 `fileData.fileUri` 则不应填 data URL。不要只根据字符串的外观判断它能否跨接口复用。[兼容接口](https://ai.google.dev/gemini-api/docs/openai)、[原生字段定义](https://ai.google.dev/api/generate-content)

### 同一个链接昨天能用，今天失效，是模型坏了吗？

先检查引用自身的有效期与权限。普通 Files 上传为 48 小时，GCS 注册最长 30 天，外部签名地址按自己的有效期；包装器输出地址也可能另有限制。只有把实际资源、接口和当前错误对齐后，才能判断下一步是否需要查模型或服务状态。[Google 文件生命周期](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-07。

- [Google 文件输入方式说明](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods) (ai.google.dev)
- [Google 图片生成与编辑文档](https://ai.google.dev/gemini-api/docs/image-generation) (ai.google.dev)
- [该案例的原始说明](https://help.apiyi.com/en/nano-banana-pro-unsupported-file-uri-type-error-fix-en.html) (help.apiyi.com)
- [Google API 定义](https://ai.google.dev/api/generate-content) (ai.google.dev)
- [File 资源定义与上传接口](https://ai.google.dev/api/files) (ai.google.dev)
- [论坛讨论](https://discuss.ai.google.dev/t/400-invalid-or-unsupported-file-uri/73951) (discuss.ai.google.dev)
- [Google OpenAI 兼容文档](https://ai.google.dev/gemini-api/docs/openai) (ai.google.dev)
- [Vercel AI 问题报告](https://github.com/vercel/ai/issues/10692) (github.com)
- [Comfy Nano Banana Pro 接口说明](https://docs.comfy.org/ja/development/comfy-router/models/google/nano-banana-pro/code) (docs.comfy.org)