最近有客戶在調用 Nano Banana Pro（模型 ID:gemini-3-pro-image-preview）進行圖生圖時，遇到了一個看起來很 "Google 風格" 的 400 報錯:
{
"status_code": 400，
"error": {
"message": "Unsupported file URI type: {{ $json.imageUrls }}. File URI must be a File API （e.g. https://generativelanguage.googleapis.com/files/<id>）， Youtube （e.g. https://www.youtube.com/watch？v=<id>）， or HTTPS （e.g. http://path/to/file）.）， or a valid gURI （e.g. gs://bucket/object"，
"type": ""，
"code": 400
}
}
這條 Nano Banana Pro 報錯 信息其實已經把"兇手"指出來了:Unsupported file URI type: {{ $json.imageUrls }}。請注意 {{ $json.imageUrls }} 是未被替換的 n8n 模板變量原文——也就是說，客戶在工作流裏寫了一個動態表達式，但是這個表達式根本沒有被引擎渲染成真正的 URL，而是被當成字符串原樣塞進了 Gemini API 的 fileUri 字段。Google 這邊自然沒法識別一個長成 {{ ... }} 的 URI，於是直接拒絕了請求。
本文基於這條真實報錯，以及 Google 官方文檔對 gemini-3-pro-image-preview 輸入格式的要求，系統拆解 5 類最常見的觸發場景，並給出每一種場景的最小可復現代碼與一次性修復方案。讀完之後，你應該能夠在 5 分鐘之內定位並修好任何一條出現 Unsupported file URI type 的失敗請求。
Nano Banana Pro 報錯核心信息一覽
在動手改代碼之前，我們先用一張表把這條報錯的關鍵信息和官方對輸入 URI 的允許格式鎖定到一屏之內。
| 維度 | 關鍵事實 |
|---|---|
| 模型 ID | gemini-3-pro-image-preview（Nano Banana Pro 在 Gemini API 中的正式名） |
| 報錯 HTTP 狀態 | 400（Bad Request，客戶端參數錯誤） |
| 報錯關鍵字段 | Unsupported file URI type |
| 真正問題位置 | 請求 body 中的 fileData.fileUri 字段 |
| 報錯裏出現的字面量 | {{ $json.imageUrls }}（未被渲染的 n8n 表達式） |
| Gemini 接受的 URI 類型 | File API URI / YouTube URL / 公網 HTTPS URL / GCS gs:// URI |
| Gemini 接受的圖片格式 | JPEG、JPG、PNG、WEBP、HEIF |
| Nano Banana Pro 輸入支持外部 URL？ | ✅ 支持（Gemini 2.5+ 模型起原生支持公網 HTTPS / 預簽名 URL） |
| 大概率根因 | n8n / Make / Zapier 等低代碼工作流的模板變量未被替換 |
🎯 快速排查建議:如果你的客戶不願意把完整請求 body 給你看，你可以讓他先在 API易 apiyi.com 控制檯用同一個
gemini-3-pro-image-preview模型 + 同一張參考圖復現一次成功的調用，然後再把失敗請求與成功請求的 body 做 diff，這是最快鎖定 Nano Banana Pro 報錯 的方式。
Nano Banana Pro 報錯 Unsupported file URI type 的 5 大成因
把所有真實案例歸類後，這條 Unsupported file URI type 報錯可以收斂到 5 個典型原因。我們按"出現頻率"從高到低排序。
原因 1:n8n / Make / Zapier 的模板變量沒有被渲染
這是當前這條具體報錯的第一嫌疑人。{{ $json.imageUrls }} 是 n8n 表達式語法，正常情況下應該在執行前被替換成上一步節點輸出的真實 URL，例如 https://cdn.example.com/uploads/abc.jpg。但有幾種典型情況會讓這個替換失敗:
- HTTP Request 節點的 Body 字段沒有點 "Expression" 模式，而是寫成了 "Fixed" 模式，導致整段 JSON 被當成純文本字符串發送；
- JSON Body 用了雙層引號嵌套，n8n 誤以爲表達式是字符串內容的一部分，跳過渲染；
- 上一步節點的輸出結構和你寫的路徑對不上——例如上一步實際輸出的是
imageUrl（單數），你卻寫了$json.imageUrls（複數），解析失敗後 n8n 把整個表達式原文返回； - Sub-node 中的表達式不會按 Item 迭代，而是固定取第一條，某些輸入下變成
undefined，序列化爲字符串後變成原文。
判斷方法:只要你看到 Gemini 的報錯裏包含 {{ ... }}，就 100% 是這一類問題，因爲正常 URL 不可能長成那樣。
原因 2:字段名拼寫錯誤，導致傳入了 undefined / null
緊隨其後的是字段名問題。客戶的代碼裏很可能存在這種情況:
// 上游接口實際返回的字段叫 imageUrl（單數）
const upstream = { imageUrl: "https://cdn.example.com/a.jpg" }；
// 但下游寫的是 imageUrls（複數，帶 s）
fileUri: upstream.imageUrls // 結果是 undefined
undefined 在被 JSON 序列化或字符串拼接時，會變成 "undefined" 這個字符串，Gemini 同樣無法識別，於是拋出和模板變量未渲染幾乎一模一樣的 400 報錯。區別在於報錯裏出現的字面量是 undefined 而不是 {{ ... }}。
原因 3:把數組當成字符串傳進了 fileUri
第三類原因常出現在"批量處理多張圖"的場景。Gemini API 的 fileData.fileUri 字段只接受單個字符串，不是數組。但很多開發者會這樣寫:
// ❌ 錯誤:把數組直接塞進 fileUri
{
"fileData": {
"fileUri": ["https://cdn.example.com/a.jpg"， "https://cdn.example.com/b.jpg"]，
"mimeType": "image/jpeg"
}
}
JSON 序列化後這個 fileUri 字段會變成 ["https://..."， "https://..."] 字符串，Gemini 解析失敗，直接報 Unsupported file URI type。正確做法是爲每張圖生成一個獨立的 parts 元素，而不是把數組塞到一個 fileUri 裏。
原因 4:URL 協議或路徑格式不被支持
第四類問題屬於"格式偏差"。Gemini API 接受的 URI 類型只有 4 種，任何超出範圍的寫法都會觸發同樣的報錯:
| URI 類型 | 示例 | 是否被 gemini-3-pro-image-preview 接受 |
|---|---|---|
| File API 路徑 | https://generativelanguage.googleapis.com/files/abc123 |
✅ |
| YouTube URL | https://www.youtube.com/watch？v=xxxxx |
✅（主要用於視頻理解） |
| 公網 HTTPS URL | https://cdn.example.com/img.jpg |
✅（Gemini 2.5+ 起原生支持） |
GCS gs:// URI |
gs://my-bucket/img.jpg |
✅（Vertex AI 路徑） |
http:// 明文 |
http://cdn.example.com/img.jpg |
⚠️ 部分情況被拒，推薦升級到 HTTPS |
file:// 本地路徑 |
file:///Users/me/a.jpg |
❌ |
data:image/...；base64， |
base64 dataURL | ❌（應放到 inlineData） |
| Pre-signed S3 URL | https://bucket.s3.amazonaws.com/...？X-Amz-... |
✅ |
| Azure SAS URL | https://account.blob.core.windows.net/...？sv=... |
✅ |
如果你直接把本地文件路徑、data: 開頭的 base64 或者私有內網 URL 塞到 fileUri，無一例外都會觸發 Nano Banana Pro 報錯。
原因 5:URL 可訪問但需要鑑權 / 返回非圖片
最後一類是"URL 看起來對了，但 Gemini 實際拉不到內容"。常見情況:
- 私有 OSS / 七牛 / Cloudinary 鏈接沒有公開權限，Gemini 拉到 403；
- 臨時簽名 URL 已經過期；
- URL 返回的不是圖片，而是 HTML 頁面（例如某些圖牀的"分享頁"，而不是直鏈）；
- URL 重定向跳轉到登錄頁；
- MIME 類型與
mimeType字段不匹配。
這類問題有時也會以 Unsupported file URI type 的形式拋出，有時則會變成另一條 400 Invalid or unsupported file uri。兩者的修復思路是一樣的:用瀏覽器無痕窗口直接訪問這條 URL，看是不是能下載到一張合法的圖片，這是最樸素也最有效的方法。
Nano Banana Pro 報錯的最小復現與一次性修復方案
把 5 大原因看完之後，接下來給出每一種場景下的最小可復現代碼 + 修復版本，可以直接複製到你的工作流或後端中替換。
修復 1:n8n 中正確傳遞 imageUrls 參數
針對客戶當前這條 Nano Banana Pro 報錯，如果他用的是 n8n 的 HTTP Request 節點，正確的寫法應該是這樣:
HTTP Request 節點配置:
- Method:
POST - URL:
https://api.apiyi.com/v1/messages（替換爲你的 API易轉發地址） - Authentication: Header Auth（放上你的 API Key）
- Body Content Type:
JSON - Specify Body: 選擇
Using JSON（而不是 Using Fields） - JSON Body（注意整段 JSON 用表達式模式，即左側紫色 fx 按鈕要點亮）:
={
"model": "gemini-3-pro-image-preview"，
"contents": [
{
"parts": [
{ "text": "把這張圖變成宮崎駿風格" }，
{
"fileData": {
"fileUri": "{{ $json.imageUrls }}"，
"mimeType": "image/jpeg"
}
}
]
}
]
}
關鍵點有 3 個:
- JSON 字符串前面有
=號，告訴 n8n 這整段是表達式，需要解析； "{{ $json.imageUrls }}"外層必須有雙引號，內層{{ }}纔會被替換成真正的字符串；- 上一步節點必須真的輸出名爲
imageUrls的字段；如果它輸出的是imageUrl（單數）或image_url，要相應改字段名。
只要這 3 點同時滿足，Unsupported file URI type 報錯就會立刻消失。
修復 2:Python / Node.js 中防止字段名 typo
如果客戶用的是後端代碼，推薦加一道輸入校驗，把 typo 暴露在請求 Gemini 之前:
import requests
def call_nano_banana_pro（prompt: str， image_url: str）:
# 防禦式校驗:在發請求前先把 None / 空串 / 模板字符串攔下來
if not image_url or not isinstance（image_url， str）:
raise ValueError（f"image_url 必須是非空字符串，當前值: {image_url！r}"）
if image_url.startswith（"{{"） or "undefined" in image_url:
raise ValueError（f"image_url 看起來是未渲染的模板變量: {image_url}"）
if not image_url.startswith（（"https://"， "gs://"））:
raise ValueError（f"image_url 必須是 https:// 或 gs:// 開頭: {image_url}"）
payload = {
"model": "gemini-3-pro-image-preview"，
"contents": [{
"parts": [
{"text": prompt}，
{"fileData": {
"fileUri": image_url，
"mimeType": "image/jpeg"
}}
]
}]
}
resp = requests.post（
"https://api.apiyi.com/v1/messages"，
headers={"Authorization": "Bearer YOUR_API_KEY"}，
json=payload，
timeout=120
）
return resp.json（）
這種"先校驗再發送"的寫法可以把 90% 的 Nano Banana Pro 報錯 攔截在調用之前，避免污染 Gemini 端的失敗日誌。
修復 3:批量圖片正確拆成多個 parts
如果你確實需要一次給 Nano Banana Pro 傳多張參考圖（例如做風格遷移 + 人物鎖定），正確的做法是爲每張圖建立獨立的 parts 元素，而不是把數組塞進 fileUri:
// ✅ 正確寫法
const imageUrls = [
"https://cdn.example.com/style.jpg"，
"https://cdn.example.com/person.jpg"
]；
const payload = {
model: "gemini-3-pro-image-preview"，
contents: [{
parts: [
{ text: "把第二張圖的人物畫成第一張圖的風格" }，
...imageUrls.map（url => （{
fileData: { fileUri: url， mimeType: "image/jpeg" }
}））
]
}]
}；
const resp = await fetch（"https://api.apiyi.com/v1/messages"， {
method: "POST"，
headers: {
"Content-Type": "application/json"，
"Authorization": "Bearer YOUR_API_KEY"
}，
body: JSON.stringify（payload）
}）；
這種寫法不僅能避免 Unsupported file URI type，還能讓 Gemini 正確理解多圖之間的語義關係。
修復 4:不可達 URL 退回到 base64 內聯
如果你拿到的 URL 是私有桶、內網地址或者臨時 URL，可能在 Gemini 服務器側根本拉不到。最穩的退路是改用 inlineData + base64:
import base64
import requests
def call_with_base64（prompt: str， local_path: str）:
with open（local_path， "rb"） as f:
b64 = base64.b64encode（f.read（））.decode（"utf-8"）
payload = {
"model": "gemini-3-pro-image-preview"，
"contents": [{
"parts": [
{"text": prompt}，
{"inlineData": {
"mimeType": "image/jpeg"，
"data": b64
}}
]
}]
}
return requests.post（
"https://api.apiyi.com/v1/messages"，
headers={"Authorization": "Bearer YOUR_API_KEY"}，
json=payload
）.json（）
注意:inlineData 用的是 data 字段（純 base64，不帶 data:image/jpeg；base64， 前綴），fileData 用的是 fileUri 字段，兩者互斥，不要同時填。
🎯 穩定性建議:對於 URL 來源不可控的場景（例如來自客戶上傳 / 第三方接口），我們建議把 圖生圖 默認走 base64 內聯 + 通過 API易 apiyi.com 這樣的中轉平臺調用
gemini-3-pro-image-preview，避免 Gemini 因爲各種網絡/權限問題間歇性拒絕外部 URL。
Nano Banana Pro 報錯排查動作清單
把上面所有內容濃縮成一份"5 分鐘排查"清單，客戶出現 Unsupported file URI type 時直接對照執行即可。
5 分鐘排查清單
| 步驟 | 動作 | 期望結果 |
|---|---|---|
| 1 | 把報錯消息中 Unsupported file URI type: 後面的字面量複製出來 |
拿到 Gemini 實際接收到的 fileUri 值 |
| 2 | 檢查這個值是不是包含 {{、undefined、null、[ |
命中 → 90% 是模板未渲染或字段名錯 |
| 3 | 用瀏覽器無痕窗口直接打開這個 URL | 期望:能下載到一張合法 JPEG/PNG/WEBP |
| 4 | 檢查 URL 協議是否爲 https:// 或 gs:// |
不是 → 改協議或換 base64 |
| 5 | 檢查是否是私有桶、過期簽名或重定向 | 是 → 換公網 URL 或改 base64 |
| 6 | 在 API易 apiyi.com 控制檯用同一個模型 + 一張已知公開圖復現 | 復現成功 → 問題在客戶端；復現失敗 → 反饋給我們 |
只要走完這 6 步，基本上沒有任何一條 Nano Banana Pro 報錯 能藏住自己的根因。
Nano Banana Pro Unsupported file URI type 常見問題 FAQ
Q1:爲什麼報錯信息裏直接寫出了 {{ $json.imageUrls }} 這串字面量？
因爲 Gemini API 在收到請求時，把 fileUri 字段的值原樣寫進了報錯消息——這是 Google 官方的標準行爲，目的就是幫你快速定位"我到底傳了什麼進去"。如果你看到的字面量長得像 {{ ... }}，這是 100% 的低代碼工作流模板變量未渲染；如果是 undefined / null，則是字段名 typo。建議先在 API易 apiyi.com 上用一個寫死的公網 URL 復現一次成功調用，再把客戶端往這套成功 body 上對齊。
Q2:Nano Banana Pro / gemini-3-pro-image-preview 到底支持哪些 URL？
按 Google 官方文檔，fileUri 接受 4 類 URI:File API 路徑（https://generativelanguage.googleapis.com/files/...）、YouTube URL（主要用於視頻理解）、公網 HTTPS URL（包括 S3 Pre-signed、Azure SAS）、GCS gs:// URI。Gemini 2.5 及更新的模型都原生支持公網 HTTPS，因此 gemini-3-pro-image-preview 不需要先把圖傳到 File API 再調用。
Q3:n8n 裏 {{ $json.imageUrls }} 沒渲染怎麼辦？
最常見的修復點有 3 個:第一，HTTP Request 節點的 JSON Body 必須開啓表達式模式（整段 JSON 前有 = 號或左側 fx 按鈕亮起）；第二，字段路徑要和上一步節點的真實輸出對得上，可以在 n8n 的 "Execute Node" 後查看 Output 面板確認字段名；第三，如果你用的是 sub-node，表達式默認只取第一條 item，要麼改用主 node，要麼先用 Item Lists 節點把數據展開。
Q4:報錯裏寫着 undefined 該怎麼修？
說明你在代碼裏訪問了一個不存在的字段。最快的修復是在調 Gemini 之前加一道斷言:assert image_url is not None and isinstance（image_url， str）；然後再去上游接口的返回值中確認字段名，常見 typo 包括 imageUrls vs imageUrl、image_url vs imageUrl、url vs uri。在生產環境建議像本文 "修復 2" 那段 Python 代碼一樣，把"非 https/gs"的字符串直接擋在請求外。
Q5:能不能把多張圖直接塞進 fileUri？
不能。fileUri 只接受單個字符串。如果要傳多張圖，正確做法是爲每張圖新建一個 { "fileData": { "fileUri": "..."， "mimeType": "..." } } 元素，然後把它們都放到同一個 parts 數組裏。這樣 Gemini 才能正確識別多圖之間的語義關係。
Q6:私有桶或者臨時簽名 URL 實在不能公開怎麼辦？
最穩的兜底方案是改用 inlineData + base64:把圖片在你這邊讀出來，base64 編碼後直接放進請求 body。這樣完全不需要 Gemini 服務器去拉外部資源，也就避開了所有"鑑權失敗 / 簽名過期 / MIME 不匹配"的坑。代價是請求體會變大，適合單圖小尺寸場景。如果你做的是高併發圖生圖，仍然建議把圖先上傳到一個公網可達的 CDN 上，再通過 API易 apiyi.com 調用 gemini-3-pro-image-preview，這樣既避免 base64 體積膨脹，也方便平臺層統一做緩存與重試。
總結:Nano Banana Pro 報錯修復後的最佳實踐
回到客戶那條具體的 Nano Banana Pro 報錯:Unsupported file URI type: {{ $json.imageUrls }}，我們已經可以非常確定地告訴他——這不是 Gemini 的問題，而是 n8n / 低代碼工作流沒有把模板變量替換成真實 URL，導致整段 {{ ... }} 字面量被原樣發到了 Gemini API。修復方法在本文 "修復 1" 裏已經給出，只要讓 HTTP Request 節點的 JSON Body 開啓表達式模式、確認上一步節點真的輸出了 imageUrls 字段，這條報錯就會立刻消失。
在更廣義的層面，Unsupported file URI type 這條報錯暴露出來的是一個非常普遍的問題:很多團隊在調用圖像 API 時缺少"輸入校驗"這一層，導致 Gemini 端拒絕請求時，根本看不出來到底是模型問題、網絡問題還是參數問題。本文給出的 5 分鐘排查清單 + Python 校驗代碼 + n8n 表達式寫法，可以直接拿來作爲團隊的標準應對動作。
🎯 最終建議:如果你正在爲客戶搭建基於 gemini-3-pro-image-preview 的圖生圖工作流，我們建議把所有 Nano Banana Pro 調用統一收斂到 API易 apiyi.com 這種中轉平臺，既能在控制檯快速復現 + diff 失敗請求，也能在 Google 自身故障時無縫切換到 Nano Banana 2 / Seedream 等同檔位模型，讓 Unsupported file URI type 這類參數錯誤第一時間被定位與修復。
作者:APIYI Team ｜ 關注 AI 大模型落地與穩定性工程，更多 Gemini 與圖像 API 實戰排查請訪問 API易 apiyi.com。
