nano banana pro api image config no size parameter id image 0 图示

Menghindari kesalahan dalam pemanggilan API Nano Banana Pro: imageConfig menentukan resolusi, jangan tambahkan parameter size

oleh

Banyak pengembang yang baru pertama kali memanggil API Nano Banana Pro (yang setara dengan model gemini-3-pro-image-preview dari Google) sering terjebak dalam masalah yang sama: menggunakan kembali parameter size: "1024x1024" dari era OpenAI / DALL-E. Akibatnya, resolusi gambar tidak berubah saat diatur, muncul error 400, atau parameter tersebut diabaikan begitu saja oleh server.

Ini adalah "bug frekuensi tinggi" yang paling umum dalam pemanggilan API Nano Banana Pro. Cara yang benar adalah: resolusi ditentukan oleh dua parameter, yaitu imageConfig.imageSize (untuk ketajaman 1K/2K/4K) dan imageConfig.aspectRatio (untuk rasio dimensi 1:1/16:9/…), jangan lagi mengirimkan field size apa pun. Artikel ini akan menjelaskan hal ini secara tuntas dalam 600 kata, lengkap dengan kode curl / Python / Node.js yang bisa langsung Anda salin dan jalankan.

nano-banana-pro-api-image-config-no-size-parameter-id 图示

Poin Utama Pemanggilan API Nano Banana Pro

Sebelum kita masuk ke kode, ingatlah tiga aturan emas ini — jika Anda memahami ketiganya, 90% isi artikel ini hanyalah detail teknis:

  1. Nama Model: Nano Banana Pro = gemini-3-pro-image-preview (juga dikenal sebagai Gemini 3 Pro Image), yang merupakan model pembuatan/pengeditan gambar dari seri Google Gemini 3. Beberapa orang menyebutnya Nano Banana 2, namun pada dasarnya itu adalah hal yang sama.
  2. Protokol Asli Gemini: Ini bukan protokol yang kompatibel dengan OpenAI Chat Completions. Jalur permintaannya adalah :generateContent, field tingkat atas pada body permintaan adalah contents + generationConfig, tidak ada messages dan tidak ada field size ala OpenAI.
  3. Resolusi = imageSize × aspectRatio: imageSize mengontrol tingkat ketajaman (512 / 1K / 2K / 4K), sedangkan aspectRatio mengontrol rasio aspek (1:1 / 16:9 / 9:16 / …). Keduanya bersama-sama menentukan piksel output akhir.

📌 Ringkasan singkat: Gunakan protokol Gemini untuk memanggil Nano Banana Pro, lupakan kebiasaan menggunakan size: "1024x1024" dari OpenAI. Layanan proksi API APIYI (apiyi.com) mempertahankan protokol asli Gemini secara penuh untuk endpoint Nano Banana Pro, sehingga penulisan imageConfig yang valid di Google juga akan berfungsi di APIYI.

Sekilas Parameter Penting Nano Banana Pro

Parameter Lokasi Fungsi Contoh Nilai
imageSize generationConfig.imageConfig Tingkat ketajaman "512" / "1K" / "2K" / "4K"
aspectRatio generationConfig.imageConfig Rasio aspek "1:1" / "16:9" / "9:16" / "4:3" dll.
responseModalities generationConfig Modalitas output ["IMAGE"] (wajib)
contents[].parts[].text contents Prompt teks Teks bebas
contents[].parts[].inline_data contents Gambar input (base64) Berisi mime_type dan data

⚠️ Field size tidak ada dalam tabel: Karena field tersebut sama sekali bukan parameter yang sah dalam protokol Gemini, jangan gunakan.

Mengapa tidak perlu menambahkan parameter size? Alasan di tingkat protokol

Ini adalah bagian paling inti dari artikel ini. Kita akan membahasnya melalui tiga lapisan agar Anda benar-benar paham.

Tingkat Protokol: Gemini dan OpenAI adalah dua spesifikasi yang berbeda

API gambar OpenAI (DALL-E 2/3, gpt-image-1) menggunakan parameter string tingkat atas size: "1024x1024"; sedangkan API gambar Google Gemini 3 dirancang dengan objek imageConfig yang bersarang, kedua spesifikasi ini sepenuhnya independen. Nano Banana Pro menggunakan protokol asli Gemini, jadi:

  • ❌ size: "1024x1024" —— Protokol Gemini tidak memiliki field ini
  • ❌ size: "1K" —— Tidak ada field ini
  • ❌ n: 4 —— Tidak ada field "hasilkan N gambar sekaligus" seperti di OpenAI
  • ✅ imageConfig.imageSize: "1K" —— Benar
  • ✅ imageConfig.aspectRatio: "16:9" —— Benar

Tingkat Perilaku: Apa yang terjadi jika tetap mengirim size?

Biasanya ada tiga skenario yang terjadi di sisi server, dan tidak ada satu pun yang Anda inginkan:

  1. Diabaikan secara diam-diam: Gateway upstream membuang field yang tidak dikenal sebagai field yang tidak valid. Anda mengira itu berhasil, padahal output yang dihasilkan tetap default 1K 1:1.
  2. Langsung error 400: Gateway dengan validasi skema yang ketat akan langsung menolak permintaan karena adanya field yang tidak dikenal.
  3. Mempengaruhi penagihan/routing: Beberapa lapisan proksi mungkin menganggap size sebagai sinyal routing dan mencocokkannya ke versi endpoint yang salah.

Tingkat Rekayasa: Beban teknis akibat kode yang berantakan

Banyak tim membungkus API dari OpenAI, Gemini, Stability, dan lainnya dalam lapisan pemanggilan yang sama, dan terbiasa menggunakan kembali "field size umum". Sekilas terlihat elegan, padahal ini adalah sarang bug. Disarankan saat memanggil antarmuka asli Gemini seperti Nano Banana Pro, gunakan jalur konversi terpisah. Petakan size secara eksplisit menjadi imageConfig.imageSize + imageConfig.aspectRatio, alih-alih meneruskan size asli begitu saja.

💡 Saran: Saat menggunakan APIYI apiyi.com untuk memanggil Nano Banana Pro, buatlah fungsi konversi parameter kecil. Ubah string seperti "1024x1024" yang biasa digunakan tim menjadi imageSize: "1K" + aspectRatio: "1:1" untuk mencegah pencampuran parameter sejak awal.

Tabel referensi lengkap imageSize × aspectRatio

nano-banana-pro-api-image-config-no-size-parameter-id 图示

Tingkatan imageSize dan Penagihan

imageSize Batas Resolusi Perkiraan Output Token Harga Satuan (Referensi) Skenario Rekomendasi
"512" Level 512×512 Lebih rendah Paling murah Thumbnail / Draft
"1K" Level 1024×1024 ~1120 ≈ $0.134 Rekomendasi default
"2K" Level 2048×2048 ~1120 ≈ $0.134 Poster HD
"4K" Level 4096×4096 ~2000 ≈ $0.24 (Lebih mahal ~80%) Kualitas cetak

💰 Catatan Biaya: 4K sekitar 80% lebih mahal daripada 1K/2K, jangan asal menggunakan 4K untuk semuanya. Untuk sebagian besar skenario Web/App, 1K sudah cukup. Gunakan 4K hanya jika benar-benar membutuhkan resolusi super tinggi. Harga satuan terbaru yang spesifik dapat dilihat di daftar harga resmi APIYI apiyi.com.

Daftar Dukungan Lengkap aspectRatio

Rasio Kegunaan
"1:1" Foto profil / Gambar kotak media sosial
"16:9" Sampul video landscape / Wallpaper desktop
"9:16" Video pendek portrait / Wallpaper ponsel
"4:3" Rasio foto tradisional landscape
"3:4" Rasio foto tradisional portrait
"3:2" / "2:3" Rasio standar DSLR
"4:5" / "5:4" Gambar Instagram
"21:9" Layar lebar sinematik
"1:4" / "4:1" Banner memanjang
"1:8" / "8:1" Penggunaan khusus yang sangat panjang

Pemetaan Kombinasi Umum → Piksel Akhir

imageSize aspectRatio Perkiraan Piksel Output
1K 1:1 1024 × 1024
1K 16:9 1024 × 576
1K 9:16 576 × 1024
2K 1:1 2048 × 2048
2K 16:9 2048 × 1152
4K 1:1 4096 × 4096
4K 9:16 2304 × 4096
4K 21:9 4096 × 1728

Catatan: Piksel aktual mungkin memiliki penyesuaian ±N piksel karena aturan penyelarasan internal model, namun tidak mempengaruhi tingkat kejernihan visual.

Berikut adalah panduan teknis untuk melakukan pemanggilan API Nano Banana Pro dengan benar.

Kode Pemanggilan Nano Banana Pro API yang Benar

Berikut adalah contoh minimal yang bisa langsung dijalankan dalam tiga bahasa pemrograman. Ketiga contoh ini melakukan hal yang sama: mengirimkan satu gambar asli + satu petunjuk (prompt), lalu menghasilkan output gambar 1K dengan rasio 1:1.

Versi curl (paling intuitif, mudah untuk debugging)

curl -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer KUNCI-APIYI-ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA...(base64 gambar asli)"
          }
        },
        {
          "text": "Ubah gambar ini menjadi gaya cyberpunk, pertahankan pose karakter"
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

Versi Python (disarankan menggunakan requests, tanpa ketergantungan SDK)

import base64
import requests

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    headers={
        "Authorization": "Bearer KUNCI-APIYI-ANDA",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [
                {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                {"text": "Ubah gambar ini menjadi gaya cyberpunk, pertahankan pose karakter"},
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "1:1",
                "imageSize": "1K",
            },
        },
    },
    timeout=120,
)

data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(out_b64))

Versi Node.js (menggunakan fetch bawaan, agar imageConfig tidak terhapus)

import fs from "node:fs";

const imgB64 = fs.readFileSync("input.png").toString("base64");

const resp = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer KUNCI-APIYI-ANDA",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { inline_data: { mime_type: "image/png", data: imgB64 } },
          { text: "Ubah gambar ini menjadi gaya cyberpunk, pertahankan pose karakter" },
        ],
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "1:1",
          imageSize: "1K",
        },
      },
    }),
  },
);

const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));

🔧 Mengapa sangat disarankan menggunakan fetch/requests bawaan: Beberapa SDK (termasuk versi awal LiteLLM atau versi tertentu dari Google Node SDK) diketahui akan memfilter imageConfig sebagai field yang tidak dikenal, sehingga imageSize/aspectRatio tidak berfungsi. Membangun body JSON secara manual akan 100% menghindari masalah ini. Jika Anda tetap ingin menggunakan SDK, pastikan sudah menggunakan versi terbaru dan lakukan console.log pada body akhir di dalam interceptor permintaan untuk memastikan.

Daftar Periksa Kesalahan: 6 Kesalahan Paling Umum

nano-banana-pro-api-image-config-no-size-parameter-id 图示

Masalah 1: Menambahkan parameter size gaya OpenAI

// ❌ Salah: size bukan field yang valid dalam protokol Gemini
{
  "contents": [...],
  "size": "1024x1024",
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}

// ✅ Benar: Hapus size, hanya gunakan imageConfig
{
  "contents": [...],
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}

Masalah 2: Penulisan nama field dengan underscore / snake_case

Field imageConfig pada antarmuka Gemini 3 menggunakan camelCase: imageSize, aspectRatio, responseModalities. Kesalahan umum:

  • ❌ image_size / aspect_ratio / response_modalities
  • ✅ imageSize / aspectRatio / responseModalities

Masalah 3: imageConfig terhapus secara diam-diam oleh SDK

Seperti disebutkan sebelumnya, beberapa versi SDK akan memfilter field yang tidak dikenal. Cara pengecekan:

  1. Cetak HTTP body yang sebenarnya sebelum dan sesudah pemanggilan SDK
  2. Gunakan mitmproxy / Charles untuk menangkap permintaan keluar yang sebenarnya
  3. Jika imageConfig hilang, gunakan fetch / requests bawaan

Masalah 4: Lupa menyertakan responseModalities

// ❌ Saat responseModalities tidak diatur, mungkin akan mengembalikan teks, bukan gambar
{ "generationConfig": { "imageConfig": {...} } }

// ✅ Harus secara eksplisit menyatakan bahwa modalitas pengembalian mencakup IMAGE
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }

Masalah 5: Tidak melakukan exponential backoff saat terkena limit 429

Saat beban upstream penuh, API akan mengembalikan respons seperti:

{ "error": { "message": "Beban upstream grup saat ini penuh, silakan coba lagi nanti", "type": "upstream_error", "code": 429 } }

Cara yang benar adalah melakukan retry dengan exponential backoff (3s → 6s → 12s), jangan langsung mencoba ulang karena hanya akan memperparah kemacetan:

import time

for attempt in range(3):
    resp = requests.post(url, json=body, headers=headers, timeout=120)
    if resp.status_code != 429:
        break
    time.sleep(3 * (2 ** attempt))   # 3s, 6s, 12s

Masalah 6: Salah posisi saat mengirim beberapa gambar referensi

Nano Banana Pro mendukung input multi-gambar (gambar asli + beberapa gambar referensi). Semua gambar harus dimasukkan sebagai beberapa item inline_data di dalam array parts, dan teks prompt diletakkan di akhir array:

// ✅ Benar: Gambar di depan, teks di belakang
"parts": [
  { "inline_data": { "mime_type": "image/png", "data": "base64 gambar asli" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64 gambar referensi 1" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64 gambar referensi 2" } },
  { "text": "Tolong migrasikan gaya gambar asli ke nada warna referensi 1, dan gunakan referensi 2 sebagai acuan komposisi" }
]

🧰 Ringkasan: Jadikan 6 poin di atas sebagai "Daftar Periksa Nano Banana Pro" internal Anda. Dengan memeriksanya setiap kali Anda membuat pemanggilan baru, Anda bisa menghindari 90% bug dasar. Endpoint Nano Banana Pro di APIYI (apiyi.com) sepenuhnya mengikuti protokol Gemini, sehingga semua tips ini berlaku.

Bedah Alur Pemanggilan Pengguna: Di Mana Titik Kesalahan Paling Sering Terjadi

nano-banana-pro-api-image-config-no-size-parameter-id 图示

Banyak pembaca mengirimkan log pemanggilan yang hampir sama dengan alur yang Anda berikan:

Frontend POST /api/generate
  → server.js mengekstrak parameter
  → Memeriksa modelKey.startsWith('nano-banana')
  → _generateViaGemini() menyusun body permintaan
  → POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
  → Mengembalikan / mencoba ulang

Mari kita tandai setiap titik yang paling rawan kesalahan:

Tahapan Masalah Umum Saran
Parameter Frontend Terbiasa mengirim size: "1024x1024" Pecah menjadi dua field: imageSize + aspectRatio
Penyusunan body server.js Tidak sengaja meneruskan field size ke Gemini Hapus field size secara eksplisit di fungsi penyusunan
Rute Model nano-banana diarahkan ke 1.5, bukan 3 Pro Tulis nama model secara ketat: gemini-3-pro-image-preview
Pengiriman Permintaan Menggunakan SDK versi dengan validasi skema Gunakan fetch native, atau update SDK ke versi terbaru
Penanganan Error 429 langsung dilempar ke pengguna Lakukan percobaan ulang dengan eksponensial backoff 3 kali
Parsing Respons Default mengambil text, padahal hasilnya IMAGE Jalur yang benar: candidates[0].content.parts[0].inline_data.data

📋 Singkatnya: Alur yang Anda lampirkan sudah benar. Selama Anda menghapus field size yang tidak perlu di tahap "ekstraksi parameter" dan memastikan server.js tidak menyisipkannya kembali ke luar generationConfig, maka seluruh alur akan berjalan lancar.

FAQ (Pertanyaan yang Sering Diajukan)

Q1: Apakah Nano Banana Pro dan Nano Banana 2 adalah hal yang sama?
Ya. Banyak orang di komunitas menyebut Gemini 3 Pro Image (gemini-3-pro-image-preview) sebagai Nano Banana 2 / Nano Banana Pro. Ketiga istilah tersebut merujuk pada model yang sama. Di APIYI apiyi.com, nama model yang digunakan harus sesuai dengan dokumentasi resmi.

Q2: Apa yang terjadi jika saya tidak mengirim imageConfig?
Model akan menggunakan nilai default internal (biasanya 1K + 1:1). Jika Anda tidak terlalu peduli dengan resolusi, Anda bisa mengabaikannya; namun jika Anda memiliki persyaratan khusus untuk ukuran gambar, Anda wajib mengirim imageConfig secara eksplisit.

Q3: Bisakah saya menggunakan protokol Gemini tetapi tetap mengirim size seperti di OpenAI?
Tidak disarankan. Protokol Gemini tidak memiliki field size. Mencampur keduanya hanya akan menyebabkan perilaku yang tidak terduga. Menggunakan imageConfig.imageSize + imageConfig.aspectRatio adalah cara yang paling aman.

Q4: Apakah memilih 4K untuk imageSize pasti menghasilkan kualitas yang lebih baik?
Detail gambar akan lebih kaya, tetapi biayanya hampir dua kali lipat (~$0,24 vs $0,134) dan waktu pembuatan lebih lama. Untuk gambar pendukung Web/App, 1K atau 2K biasanya sudah cukup. Disarankan untuk menguji satu set gambar bisnis nyata dan membandingkannya secara visual sebelum memutuskan.

Q5: Apa perbedaan antara memanggil Nano Banana Pro melalui APIYI apiyi.com dengan memanggil API resmi Google secara langsung?
APIYI menyediakan autentikasi terpadu ala OpenAI (Bearer Token) + akses yang stabil di dalam negeri + penagihan terpadu, sementara protokol pemanggilan tetap mengikuti format asli Gemini. Artinya, imageConfig / aspectRatio / responseModalities yang Anda lihat di dokumentasi resmi Google sepenuhnya setara di APIYI apiyi.com.

Q6: Mengapa saya sudah mengatur imageSize: "2K" tapi outputnya tetap 1K?
3 penyebab paling umum: (1) Menggunakan SDK yang memfilter field tidak dikenal, (2) Nama field ditulis sebagai image_size, (3) Level bersarang generationConfig salah. Tangkap paket jaringan yang sebenarnya untuk memastikan body sesuai dengan spesifikasi sebelum memeriksa sisi server.

Q7: Apa yang harus dilakukan jika terjadi limitasi 429 dari upstream?
Lakukan percobaan ulang dengan eksponensial backoff (3s/6s/12s). Jika bisnis Anda sensitif terhadap latensi, pertimbangkan untuk beralih ke grup yang berbeda di ruang kerja APIYI apiyi.com atau ajukan kuota independen. Jangan pernah menulis loop tak terbatas untuk mencoba ulang secara instan, karena Anda akan terus terkena kebijakan limitasi.

Q8: Apakah ada batasan jumlah untuk input multi-gambar?
Interface Gemini 3 image memiliki batasan pada total ukuran gambar untuk satu permintaan (biasanya dihitung dalam MB, silakan cek dokumentasi resmi). Disarankan untuk tidak melebihi 4-5 gambar referensi, dengan ukuran yang dikontrol (resize terlebih dahulu sebelum base64), jika tidak, Anda akan memicu error 413 / timeout.

Ringkasan: Memasukkan "Metode Dua Parameter Resolusi" ke dalam Memori Otot

Jika hanya ada satu hal yang perlu diingat, inilah poinnya:

Resolusi output akhir Nano Banana Pro = imageConfig.imageSize × imageConfig.aspectRatio, jangan lagi mengirimkan field size bergaya OpenAI.

Checklist lengkap:

  • ✅ Nama model: gemini-3-pro-image-preview
  • ✅ Endpoint: /v1beta/models/.../generateContent
  • ✅ generationConfig.imageConfig.imageSize ∈ 512 / 1K / 2K / 4K
  • ✅ generationConfig.imageConfig.aspectRatio ∈ 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 / …
  • ✅ generationConfig.responseModalities wajib menyertakan "IMAGE"
  • ✅ Input multi-gambar diletakkan di dalam array parts, petunjuk teks diletakkan di bagian akhir
  • ✅ Limit rate 429 gunakan exponential backoff (3s/6s/12s)
  • ❌ Jangan kirim size: "1024x1024"
  • ❌ Jangan tulis image_size / aspect_ratio (format snake_case salah)
  • ❌ Jangan percaya pada SDK lama yang akan memfilter field tidak dikenal, pastikan dulu dengan melakukan packet capture

📢 Pesan terakhir: Jika Anda sedang mengakses Nano Banana Pro melalui APIYI apiyi.com, cukup salin template kode curl / Python / Node.js yang diberikan di artikel ini. Semua parameter sepenuhnya mematuhi protokol asli Gemini, tinggal salin-tempel → ganti kunci API → jalankan.

Penulis: Tim APIYI · Terus menyusun praktik terbaik pemanggilan API Model Bahasa Besar AI · apiyi.com

Tinggalkan komentar