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

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 文件输入方式说明

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

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

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

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

商户曾报告报错中直接出现 {{ $json.imageUrls }} 的未展开表达式案例，这能说明该症状值得检查，却不能证明所有同名错误都由它导致，也不能据此承诺修复成功率。该案例的原始说明 原生 Part 和 FileData 的字段类型以 Google API 定义为准；不同包装器未必返回相同错误文字。

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

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

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

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

{
  "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 则有各自的参数写法；应保持所用序列化器的文档写法一致，不把几套格式拼成一个请求。原生请求与字段定义

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

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

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

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

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

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

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，且有该模型的调用权限；执行会发送图片并可能产生费用。本文示例已做本地构造检查，没有代你执行上传或模型调用。

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 资源定义与上传接口

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

标准上传文件保留 48 小时，复用前应检查 expirationTime 或获取当前资源状态；已经失效就重新上传并更新缓存 URI。不要把原封不动的失效 URI 反复提交，也不要把这 48 小时套到所有注册资源或第三方图片地址上。Google 文件输入与生命周期说明

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

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

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

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

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

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

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

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

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

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

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

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

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

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 图片响应与编辑示例

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

常见追问

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

不一定。当前原生 generateContent 支持符合条件的公网 HTTPS 和预签名地址，Gemini 2.0 不支持这条方式；还需核对所用模型与包装器。图片只在本地时，可以读取字节后内联；需要复用时可上传并使用返回 URI。官方输入方式说明

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

字段和接口不同。Gemini OpenAI 兼容图片理解示例把 data URL 放在 image_url.url；原生 inlineData.data 要无前缀的 raw base64，原生 fileData.fileUri 则不应填 data URL。不要只根据字符串的外观判断它能否跨接口复用。兼容接口、原生字段定义

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

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