|

Pemecahan Masalah Lengkap Kesalahan Unsupported file URI type pada Nano Banana Pro: 5 Penyebab Utama dan Solusi Sekali Jalan

ByAPIYI - Stable and affordable AI API

Baru-baru ini, ada klien yang mengalami error 400 "khas Google" saat melakukan pemanggilan Nano Banana Pro (ID model: gemini-3-pro-image-preview) untuk fitur gambar ke gambar:

{
  "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
  }
}

Pesan error Nano Banana Pro ini sebenarnya sudah menunjukkan "pelakunya": Unsupported file URI type: {{ $json.imageUrls }}. Perhatikan bahwa {{ $json.imageUrls }} adalah variabel template n8n yang belum dirender—artinya, klien menulis ekspresi dinamis di alur kerja (workflow), tetapi ekspresi ini tidak dirender oleh mesin menjadi URL yang sebenarnya, melainkan dimasukkan mentah-mentah sebagai string ke dalam kolom fileUri pada API Gemini. Google tentu saja tidak bisa mengenali URI yang berbentuk {{ ... }}, sehingga permintaan tersebut langsung ditolak.

Berdasarkan error nyata ini, serta persyaratan format input dokumentasi resmi Google untuk gemini-3-pro-image-preview, artikel ini menguraikan 5 skenario pemicu paling umum dan memberikan kode reproduksi minimal serta solusi perbaikan instan untuk setiap skenario. Setelah membaca ini, Anda seharusnya bisa menemukan dan memperbaiki setiap permintaan yang gagal dengan pesan Unsupported file URI type dalam waktu kurang dari 5 menit.

nano-banana-pro-unsupported-file-uri-type-error-fix-id 图示

Ringkasan Informasi Utama Error Nano Banana Pro

Sebelum memperbaiki kode, mari kita rangkum informasi penting mengenai error ini dan format URI yang diizinkan secara resmi dalam satu tabel.

Dimensi Fakta Kunci
ID Model gemini-3-pro-image-preview (nama resmi Nano Banana Pro di API Gemini)
Status HTTP Error 400 (Bad Request, kesalahan parameter klien)
Bidang Error Utama Unsupported file URI type
Lokasi Masalah Sebenarnya Bidang fileData.fileUri dalam body permintaan
Literal yang Muncul di Error {{ $json.imageUrls }} (ekspresi n8n yang belum dirender)
Tipe URI yang Diterima Gemini URI File API / URL YouTube / URL HTTPS publik / URI GCS gs://
Format Gambar yang Diterima Gemini JPEG, JPG, PNG, WEBP, HEIF
Apakah Nano Banana Pro mendukung URL eksternal? ✅ Ya (model Gemini 2.5+ mendukung URL HTTPS publik / URL pre-signed secara native)
Penyebab Utama yang Mungkin Variabel template pada alur kerja low-code seperti n8n / Make / Zapier belum diganti

🎯 Saran Pemecahan Masalah Cepat: Jika klien Anda enggan memperlihatkan body permintaan lengkap, minta mereka untuk melakukan pemanggilan sukses di konsol APIYI (apiyi.com) menggunakan model gemini-3-pro-image-preview yang sama + gambar referensi yang sama, lalu lakukan diff antara body permintaan yang gagal dan yang sukses. Ini adalah cara tercepat untuk melacak error Nano Banana Pro.

Setelah mengelompokkan semua kasus nyata, pesan kesalahan Unsupported file URI type dapat diringkas menjadi 5 penyebab utama. Kita urutkan berdasarkan "frekuensi kemunculan" dari yang tertinggi ke terendah.

Penyebab 1: Variabel template n8n / Make / Zapier tidak dirender

Ini adalah tersangka utama dari pesan kesalahan spesifik ini. {{ $json.imageUrls }} adalah sintaks ekspresi n8n yang seharusnya diganti dengan URL asli dari output langkah sebelumnya sebelum eksekusi, misalnya https://cdn.example.com/uploads/abc.jpg. Namun, ada beberapa kondisi umum yang menyebabkan penggantian ini gagal:

  1. Bidang Body pada node HTTP Request tidak diatur ke mode "Expression", melainkan mode "Fixed", sehingga seluruh JSON dikirim sebagai string teks biasa;
  2. JSON Body menggunakan tanda kutip ganda bersarang, sehingga n8n salah mengira ekspresi tersebut adalah bagian dari konten string dan melewatkan proses render;
  3. Struktur output node sebelumnya tidak cocok dengan jalur yang Anda tulis—misalnya, output sebenarnya adalah imageUrl (tunggal), tetapi Anda menulis $json.imageUrls (jamak), sehingga setelah gagal diurai, n8n mengembalikan ekspresi aslinya;
  4. Ekspresi dalam sub-node tidak melakukan iterasi per Item, melainkan mengambil item pertama secara tetap, yang pada input tertentu menjadi undefined, dan setelah diserialisasi menjadi string, ia berubah menjadi teks aslinya.

Cara mendeteksi: Jika Anda melihat pesan kesalahan Gemini berisi {{ ... }}, maka 100% ini adalah masalahnya, karena URL yang valid tidak mungkin berbentuk seperti itu.

Penyebab 2: Kesalahan penulisan nama bidang, menyebabkan input menjadi undefined / null

Masalah nama bidang sering menyusul di urutan berikutnya. Kemungkinan besar ada kondisi seperti ini dalam kode pengguna:

// Bidang yang dikembalikan oleh antarmuka upstream sebenarnya bernama imageUrl (tunggal)
const upstream = { imageUrl: "https://cdn.example.com/a.jpg" };

// Namun downstream menulis imageUrls (jamak, dengan s)
fileUri: upstream.imageUrls   // Hasilnya adalah undefined

Saat undefined diserialisasi ke JSON atau digabungkan ke dalam string, ia akan berubah menjadi string "undefined". Gemini juga tidak dapat mengenalinya, sehingga memunculkan kesalahan 400 yang hampir identik dengan variabel template yang tidak dirender. Bedanya, literal yang muncul dalam pesan kesalahan adalah undefined dan bukan {{ ... }}.

Penyebab 3: Mengirim array sebagai string ke dalam fileUri

Penyebab ketiga sering muncul dalam skenario "pemrosesan banyak gambar sekaligus". Bidang fileData.fileUri pada API Gemini hanya menerima satu string, bukan array. Namun, banyak pengembang menulisnya seperti ini:

// ❌ Salah: Memasukkan array langsung ke fileUri
{
  "fileData": {
    "fileUri": ["https://cdn.example.com/a.jpg", "https://cdn.example.com/b.jpg"],
    "mimeType": "image/jpeg"
  }
}

Setelah diserialisasi JSON, bidang fileUri ini akan menjadi string ["https://...", "https://..."]. Gemini gagal mengurainya dan langsung melaporkan Unsupported file URI type. Cara yang benar adalah membuat elemen parts terpisah untuk setiap gambar, bukan memasukkan array ke dalam satu fileUri.

Penyebab 4: Protokol URL atau format jalur tidak didukung

Masalah keempat termasuk dalam kategori "penyimpangan format". Hanya ada 4 jenis URI yang diterima oleh API Gemini, dan penulisan di luar jangkauan tersebut akan memicu kesalahan yang sama:

Jenis URI Contoh Diterima oleh gemini-3-pro-image-preview?
Jalur File API https://generativelanguage.googleapis.com/files/abc123 ✅
URL YouTube https://www.youtube.com/watch?v=xxxxx ✅ (terutama untuk pemahaman video)
URL HTTPS Publik https://cdn.example.com/img.jpg ✅ (didukung secara native sejak Gemini 2.5+)
URI GCS gs:// gs://my-bucket/img.jpg ✅ (jalur Vertex AI)
http:// plain text http://cdn.example.com/img.jpg ⚠️ Ditolak dalam beberapa kasus, disarankan upgrade ke HTTPS
Jalur lokal file:// file:///Users/me/a.jpg ❌
data:image/...;base64, dataURL base64 ❌ (seharusnya diletakkan di inlineData)
URL Pre-signed S3 https://bucket.s3.amazonaws.com/...?X-Amz-... ✅
URL Azure SAS https://account.blob.core.windows.net/...?sv=... ✅

Jika Anda memasukkan jalur file lokal, base64 yang diawali data:, atau URL jaringan internal pribadi ke dalam fileUri, semuanya akan memicu kesalahan Nano Banana Pro.

Penyebab 5: URL dapat diakses tetapi memerlukan otorisasi / tidak mengembalikan gambar

Kategori terakhir adalah "URL terlihat benar, tetapi Gemini tidak bisa mengambil kontennya". Situasi umum:

  • Tautan OSS pribadi / Qiniu / Cloudinary tidak memiliki izin publik, Gemini mendapatkan 403;
  • URL tanda tangan sementara sudah kedaluwarsa;
  • URL tidak mengembalikan gambar, melainkan halaman HTML (misalnya "halaman berbagi" dari penyedia hosting gambar, bukan tautan langsung);
  • URL melakukan pengalihan (redirect) ke halaman login;
  • Tipe MIME tidak cocok dengan bidang mimeType.

Masalah ini terkadang muncul sebagai Unsupported file URI type, dan terkadang berubah menjadi 400 Invalid or unsupported file uri. Solusi untuk keduanya sama: Gunakan jendela penyamaran (incognito) di browser untuk mengakses URL tersebut secara langsung, lihat apakah Anda bisa mengunduh gambar yang valid. Ini adalah cara yang paling sederhana namun paling efektif.

nano-banana-pro-unsupported-file-uri-type-error-fix-id 图示

Minimal Reproducible Error & One-Time Fix for Nano Banana Pro

Setelah memahami 5 penyebab utama, berikut adalah kode minimal yang dapat direproduksi + versi perbaikan untuk setiap skenario. Anda bisa langsung menyalinnya ke dalam alur kerja atau backend Anda.

Perbaikan 1: Meneruskan parameter imageUrls dengan benar di n8n

Untuk error Nano Banana Pro yang dialami pelanggan saat ini, jika mereka menggunakan node HTTP Request di n8n, berikut adalah penulisan yang benar:

Konfigurasi Node HTTP Request:

  • Method: POST
  • URL: https://api.apiyi.com/v1/messages (ganti dengan alamat layanan proksi API APIYI Anda)
  • Authentication: Header Auth (masukkan kunci API Anda)
  • Body Content Type: JSON
  • Specify Body: Pilih Using JSON (bukan Using Fields)
  • JSON Body (pastikan seluruh JSON dalam mode ekspresi, tombol fx berwarna ungu di sebelah kiri harus aktif):
={
  "model": "gemini-3-pro-image-preview",
  "contents": [
    {
      "parts": [
        { "text": "Ubah gambar ini menjadi gaya Studio Ghibli" },
        {
          "fileData": {
            "fileUri": "{{ $json.imageUrls }}",
            "mimeType": "image/jpeg"
          }
        }
      ]
    }
  ]
}

Ada 3 poin krusial:

  1. Harus ada tanda = di depan string JSON untuk memberi tahu n8n bahwa ini adalah ekspresi yang perlu diurai;
  2. "{{ $json.imageUrls }}" harus diapit tanda kutip ganda agar {{ }} di dalamnya diganti dengan string yang sebenarnya;
  3. Node sebelumnya harus benar-benar menghasilkan field bernama imageUrls; jika outputnya adalah imageUrl (tunggal) atau image_url, sesuaikan nama field-nya.

Selama 3 poin ini terpenuhi, error Unsupported file URI type akan langsung hilang.

Perbaikan 2: Mencegah typo nama field di Python / Node.js

Jika menggunakan kode backend, disarankan untuk menambahkan validasi input agar typo terdeteksi sebelum dikirim ke Gemini:

import requests

def call_nano_banana_pro(prompt: str, image_url: str):
    # Validasi defensif: cegah None / string kosong / string template sebelum mengirim request
    if not image_url or not isinstance(image_url, str):
        raise ValueError(f"image_url harus berupa string non-kosong, nilai saat ini: {image_url!r}")
    if image_url.startswith("{{") or "undefined" in image_url:
        raise ValueError(f"image_url terlihat seperti variabel template yang belum dirender: {image_url}")
    if not image_url.startswith(("https://", "gs://")):
        raise ValueError(f"image_url harus diawali dengan https:// atau 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()

Cara "validasi sebelum kirim" ini dapat memblokir 90% error Nano Banana Pro sebelum pemanggilan model dilakukan, sehingga log kegagalan di sisi Gemini tetap bersih.

Perbaikan 3: Memecah gambar batch menjadi beberapa parts dengan benar

Jika Anda perlu mengirim beberapa gambar referensi ke Nano Banana Pro (misalnya untuk transfer gaya + penguncian wajah), cara yang benar adalah membuat elemen parts terpisah untuk setiap gambar, bukan memasukkan array ke dalam fileUri:

// ✅ Penulisan yang benar
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: "Gambarkan orang di foto kedua dengan gaya foto pertama" },
      ...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)
});

Cara ini tidak hanya menghindari Unsupported file URI type, tetapi juga membantu Gemini memahami hubungan semantik antar gambar dengan benar.

Perbaikan 4: Kembali ke inline base64 jika URL tidak dapat diakses

Jika URL yang Anda miliki berasal dari bucket privat, jaringan internal, atau URL sementara, server Gemini mungkin tidak dapat mengambilnya. Solusi paling aman adalah menggunakan 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()

Catatan: inlineData menggunakan field data (base64 murni, tanpa prefix data:image/jpeg;base64,), sedangkan fileData menggunakan field fileUri. Keduanya bersifat eksklusif, jangan diisi bersamaan.

🎯 Saran Stabilitas: Untuk skenario di mana sumber URL tidak terkontrol (misalnya dari unggahan pelanggan/API pihak ketiga), kami menyarankan agar gambar ke gambar menggunakan base64 inline + pemanggilan model gemini-3-pro-image-preview melalui platform layanan proksi API seperti APIYI (apiyi.com) untuk menghindari penolakan URL eksternal oleh Gemini akibat masalah jaringan/izin.

Daftar Periksa Pemecahan Masalah Nano Banana Pro

Berikut adalah daftar periksa "5 menit" yang merangkum semua poin di atas. Jika pelanggan mengalami Unsupported file URI type, cukup gunakan daftar ini.

Daftar Periksa 5 Menit

Langkah Tindakan Hasil yang Diharapkan
1 Salin literal setelah Unsupported file URI type: dari pesan error Mendapatkan nilai fileUri yang sebenarnya diterima Gemini
2 Periksa apakah nilai tersebut mengandung {{, undefined, null, [ Jika ya → 90% adalah template yang belum dirender atau salah nama field
3 Buka URL tersebut langsung di browser (mode penyamaran) Harapan: Berhasil mengunduh file JPEG/PNG/WEBP yang valid
4 Periksa apakah protokol URL adalah https:// atau gs:// Jika tidak → Ubah protokol atau gunakan base64
5 Periksa apakah itu bucket privat, tanda tangan kedaluwarsa, atau redirect Jika ya → Gunakan URL publik atau gunakan base64
6 Coba reproduksi di konsol APIYI (apiyi.com) dengan model yang sama + gambar publik Berhasil → Masalah di sisi klien; Gagal → Laporkan kepada kami

Dengan mengikuti 6 langkah ini, hampir tidak ada error Nano Banana Pro yang bisa menyembunyikan akar penyebabnya.

FAQ: Masalah Umum "Unsupported file URI type" pada Nano Banana Pro

Q1: Mengapa pesan error menampilkan literal {{ $json.imageUrls }} secara langsung?

Karena saat Gemini API menerima permintaan, ia menuliskan nilai kolom fileUri ke dalam pesan error—ini adalah perilaku standar Google untuk membantu Anda melacak "apa sebenarnya yang saya kirimkan". Jika Anda melihat literal seperti {{ ... }}, itu 100% berarti variabel template alur kerja low-code belum dirender; jika muncul undefined / null, berarti ada kesalahan pengetikan (typo) pada nama kolom. Disarankan untuk mencoba melakukan pemanggilan yang berhasil dengan URL publik statis di APIYI (apiyi.com) terlebih dahulu, lalu sesuaikan body klien Anda dengan format yang berhasil tersebut.

Q2: URL mana saja yang didukung oleh Nano Banana Pro / gemini-3-pro-image-preview?

Menurut dokumentasi resmi Google, fileUri menerima 4 jenis URI: jalur File API (https://generativelanguage.googleapis.com/files/...), URL YouTube (terutama untuk pemahaman video), URL HTTPS publik (termasuk S3 Pre-signed, Azure SAS), dan URI GCS gs://. Model Gemini 2.5 dan yang lebih baru mendukung HTTPS publik secara native, sehingga gemini-3-pro-image-preview tidak perlu mengunggah gambar ke File API terlebih dahulu sebelum melakukan pemanggilan.

Q3: Apa yang harus dilakukan jika {{ $json.imageUrls }} di n8n tidak dirender?

Ada 3 poin perbaikan yang paling umum: Pertama, JSON Body pada node HTTP Request harus mengaktifkan mode ekspresi (ada tanda = di depan seluruh JSON atau tombol fx di sebelah kiri menyala); Kedua, jalur kolom harus sesuai dengan output sebenarnya dari node sebelumnya. Anda dapat memeriksa panel Output setelah "Execute Node" di n8n untuk memastikan nama kolomnya; Ketiga, jika Anda menggunakan sub-node, ekspresi secara default hanya mengambil item pertama. Anda bisa beralih ke node utama atau menggunakan node Item Lists untuk menguraikan data terlebih dahulu.

Q4: Bagaimana cara memperbaiki error yang bertuliskan undefined?

Itu berarti Anda mengakses kolom yang tidak ada di dalam kode. Perbaikan tercepat adalah menambahkan pernyataan (assertion) sebelum memanggil Gemini: assert image_url is not None and isinstance(image_url, str); kemudian periksa kembali nama kolom dari nilai balik antarmuka (API) upstream. Typo yang umum terjadi termasuk imageUrls vs imageUrl, image_url vs imageUrl, atau url vs uri. Di lingkungan produksi, disarankan untuk memblokir string yang bukan "https/gs" agar tidak masuk ke permintaan, seperti contoh kode Python pada bagian "Perbaikan 2" di artikel ini.

Q5: Bisakah saya memasukkan beberapa gambar sekaligus ke dalam fileUri?

Tidak bisa. fileUri hanya menerima satu string. Jika Anda ingin mengirim beberapa gambar, cara yang benar adalah membuat elemen { "fileData": { "fileUri": "...", "mimeType": "..." } } baru untuk setiap gambar, lalu masukkan semuanya ke dalam array parts yang sama. Dengan cara ini, Gemini dapat mengenali hubungan semantik antar gambar dengan benar.

Q6: Apa yang harus dilakukan jika bucket privat atau URL tanda tangan sementara tidak bisa dipublikasikan?

Solusi paling aman adalah menggunakan inlineData + base64: baca gambar di sisi Anda, lakukan pengkodean base64, lalu masukkan langsung ke dalam body permintaan. Dengan cara ini, server Gemini tidak perlu menarik sumber daya eksternal, sehingga menghindari semua masalah seperti "kegagalan autentikasi / tanda tangan kedaluwarsa / MIME tidak cocok". Konsekuensinya, body permintaan akan menjadi lebih besar, sehingga cocok untuk skenario gambar tunggal berukuran kecil. Jika Anda melakukan pemrosesan gambar ke gambar dengan konkurensi tinggi, tetap disarankan untuk mengunggah gambar ke CDN yang dapat diakses publik terlebih dahulu, lalu panggil gemini-3-pro-image-preview melalui APIYI (apiyi.com). Ini tidak hanya menghindari pembengkakan ukuran base64, tetapi juga memudahkan platform untuk melakukan caching dan percobaan ulang (retry).

nano-banana-pro-unsupported-file-uri-type-error-fix-id 图示

Kesimpulan: Praktik Terbaik Setelah Memperbaiki Error Nano Banana Pro

Kembali ke error spesifik Nano Banana Pro yang dialami pelanggan: Unsupported file URI type: {{ $json.imageUrls }}, kita sudah bisa memastikan dengan yakin bahwa—ini bukan masalah Gemini, melainkan n8n / alur kerja low-code yang tidak mengganti variabel template menjadi URL yang sebenarnya, sehingga literal {{ ... }} dikirim apa adanya ke Gemini API. Metode perbaikannya sudah diberikan pada bagian "Perbaikan 1" di artikel ini. Selama Anda mengaktifkan mode ekspresi pada JSON Body di node HTTP Request dan memastikan node sebelumnya benar-benar mengeluarkan kolom imageUrls, error ini akan langsung hilang.

Dalam cakupan yang lebih luas, error Unsupported file URI type mengungkap masalah yang sangat umum: banyak tim kekurangan lapisan "validasi input" saat memanggil API gambar, sehingga ketika Gemini menolak permintaan, sulit untuk mengetahui apakah itu masalah model, masalah jaringan, atau masalah parameter. Daftar periksa 5 menit + kode validasi Python + cara penulisan ekspresi n8n yang diberikan dalam artikel ini dapat langsung digunakan sebagai standar operasional tim Anda.

🎯 Saran Akhir: Jika Anda sedang membangun alur kerja pembuatan gambar berbasis gemini-3-pro-image-preview untuk klien, kami sarankan untuk memusatkan semua pemanggilan Nano Banana Pro ke platform layanan proksi API seperti APIYI (apiyi.com). Hal ini memungkinkan Anda untuk melakukan reproduksi cepat + diff permintaan yang gagal di konsol, serta beralih dengan mulus ke model setara seperti Nano Banana 2 / Seedream saat terjadi gangguan pada Google, sehingga kesalahan parameter seperti Unsupported file URI type dapat segera diidentifikasi dan diperbaiki.

Penulis: Tim APIYI ｜ Fokus pada implementasi Model Bahasa Besar AI dan rekayasa stabilitas. Untuk panduan praktis lainnya mengenai Gemini dan API gambar, silakan kunjungi APIYI di apiyi.com.

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts