Praktik API Pembuatan Gambar Multi-putaran Nano Banana Pro: Membangun Pembuatan Gambar dengan Jendela Konteks dalam 3 Langkah

Catatan Penulis: Analisis mendalam mengenai struktur bidang API pembuatan gambar multi-putaran Nano Banana Pro (gemini-3-pro-image-preview), konstruksi array contents, mekanisme thoughtSignature, dan implementasi kode praktis.

Banyak pengembang yang baru pertama kali menggunakan Nano Banana Pro mengalami kebingungan yang sama: di antarmuka web gemini.google.com, Anda bisa terus bertanya "ganti latar belakang menjadi senja" atau "tambahkan seekor kucing", dan model akan mengingat gambar sebelumnya dengan sempurna. Namun, saat memanggil API resmi, model seolah-olah "lupa ingatan". Penyebabnya adalah API Gemini bersifat stateless (tanpa status), sehingga konteks multi-putaran harus dikonstruksi secara manual oleh pemanggil. Artikel ini akan menjelaskan secara tuntas bidang dasar API pembuatan gambar multi-putaran Nano Banana Pro, implementasi SDK Python dan REST, serta mekanisme thoughtSignature yang krusial, membantu Anda membangun pengalaman pembuatan gambar dengan konteks yang lancar seperti di versi web dalam 3 langkah.

Nilai Inti: Setelah membaca artikel ini, Anda akan menguasai cara konstruksi array contents yang benar, mampu mengimplementasikan alur kerja multi-putaran "edit berdasarkan gambar sebelumnya" di aplikasi Anda sendiri, serta menghindari tiga jebakan utama: "gambar terlupakan", "pemborosan token", dan "kehilangan signature".

Poin Utama Pembuatan Gambar Multi-putaran Nano Banana Pro

Perbedaan Esensial antara Pembuatan Gambar Multi-putaran dan Agen Versi Web

gemini.google.com adalah aplikasi agen yang dibangun oleh Google. Di sisi frontend, mereka membantu Anda mengelola "status percakapan" yang lengkap (termasuk teks setiap putaran, gambar yang dihasilkan, dan tanda tangan pemikiran). Setiap kali Anda memasukkan pesan baru, agen ini akan membungkus seluruh riwayat dan mengirimkannya ke model dasar sekaligus. Itulah mengapa pengalaman di versi web terasa sangat lancar—semua pekerjaan "ingatan" ditangani oleh agen tersebut.

Namun, saat Anda memanggil API generateContent secara langsung, Anda mendapatkan antarmuka pemanggilan model yang "telanjang". Setiap permintaan HTTP adalah inferensi independen; model tidak memiliki konsep tentang percakapan Anda sebelumnya. Untuk mereplikasi pengalaman multi-putaran versi web, pada dasarnya Anda mengimplementasikan agen sendiri di dalam kode Anda—mengisi pesan user, respons model (termasuk gambar dan tanda tangan) ke dalam contents sesuai spesifikasi, lalu mengirimkan permintaan.

Penjelasan Mendalam Struktur Bidang Pembuatan Gambar Multi-putaran Nano Banana Pro

Spesifikasi Inti Array contents

contents adalah bidang standar Gemini API untuk merepresentasikan riwayat percakapan. Ini adalah array JSON di mana setiap elemen mewakili satu putaran percakapan:

Berikut adalah contoh badan permintaan (request body) untuk percakapan dua putaran yang lengkap:

{
  "contents": [
    {"role": "user", "parts": [{"text": "Buatkan gambar anjing golden retriever yang sedang berlari di pantai"}]},
    {"role": "model", "parts": [
      {"inline_data": {"mime_type": "image/png", "data": "<base64 gambar hasil putaran pertama>"}},
      {"thought_signature": "<tanda tangan terenkripsi>"}
    ]},
    {"role": "user", "parts": [{"text": "Ubah latarnya menjadi suasana senja"}]}
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
  }
}

Dua Cara Mengirim Balik Gambar

Pada permintaan putaran kedua, model harus dapat "melihat" gambar yang dihasilkan pada putaran pertama. Nano Banana Pro mendukung dua metode pengiriman balik:

# Metode 1: inline_data menyematkan base64 (cocok untuk gambar kecil, sederhana dan langsung)
{
    "inline_data": {
        "mime_type": "image/png",
        "data": base64.b64encode(image_bytes).decode()
    }
}

# Metode 2: file_data merujuk ke sumber daya yang diunggah melalui Files API (cocok untuk gambar besar atau penggunaan ulang)
{
    "file_data": {
        "mime_type": "image/png",
        "file_uri": "files/abc123xyz"
    }
}

Tips Penting: inline_data adalah cara yang paling umum digunakan untuk pemanggilan langsung dan cocok untuk skenario sekali pakai; mode referensi file_data cocok untuk skenario di mana Anda perlu menggunakan kembali gambar besar yang sama dalam beberapa putaran, yang dapat secara signifikan mengurangi ukuran badan permintaan dan beban unggah.

Memulai Cepat Pembuatan Gambar Multi-putaran Nano Banana Pro

Contoh Minimalis (Manajemen Otomatis oleh Python SDK)

Jika Anda menggunakan SDK Python resmi, penulisan paling ringkas hanya membutuhkan 10 baris:

from google import genai

client = genai.Client(api_key="KUNCI_API_ANDA")
chat = client.chats.create(model="gemini-3-pro-image-preview")

# Putaran pertama: menghasilkan gambar awal
r1 = chat.send_message("Buatkan gambar anjing golden retriever yang sedang berlari di pantai")

# Putaran kedua: mengedit berdasarkan gambar pertama (objek chat secara otomatis membawa riwayat)
r2 = chat.send_message("Ubah latarnya menjadi suasana senja, tambahkan seekor burung camar yang terbang")

# Putaran ketiga: menambahkan modifikasi lebih lanjut
r3 = chat.send_message("Ubah warna anjingnya menjadi cokelat tua")

Objek chat secara internal mengelola daftar contents yang lengkap (termasuk thoughtSignature setiap putaran), sehingga pengembang tidak perlu memusingkan detail bidang. Setiap send_message akan secara otomatis membungkus dan mengirimkan riwayat percakapan.

import openai
import base64

client = openai.OpenAI(
    api_key="KUNCI_API_ANDA",
    base_url="https://vip.apiyi.com/v1"
)

# Kelola daftar messages lokal (konsep yang sama dengan contents)
messages = [
    {"role": "user", "content": "Buatkan gambar anjing golden retriever yang sedang berlari di pantai"}
]

# Putaran pertama
response1 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)
img1_url = response1.choices[0].message.content  # Ekstrak URL gambar atau base64

# Tambahkan respons model ke dalam riwayat
messages.append({"role": "assistant", "content": img1_url})

# Putaran kedua: tambahkan instruksi baru
messages.append({"role": "user", "content": "Ubah latarnya menjadi suasana senja"})
response2 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)

# Lanjutkan putaran ketiga...
messages.append({"role": "assistant", "content": response2.choices[0].message.content})
messages.append({"role": "user", "content": "Tambahkan seekor burung camar yang terbang"})
response3 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)

Saran: Untuk skenario pengeditan multi-putaran, disarankan untuk menggunakan objek chat dari SDK atau mengelola daftar messages lokal agar tidak perlu menggabungkan contents secara manual setiap saat. Anda bisa mendaftar untuk mendapatkan kuota gratis di APIYI (apiyi.com), jalankan alur kerja dengan SDK terlebih dahulu sebelum mempertimbangkan optimasi REST.

Konstruksi Manual REST untuk Percakapan Multi-putaran Nano Banana Pro

Implementasi REST Murni Tanpa Ketergantungan SDK

Dalam skenario tertentu (seperti proksi sisi server, node ComfyUI, atau platform low-code), Anda mungkin tidak bisa menggunakan SDK resmi dan perlu menyusun permintaan REST secara langsung. Berikut adalah panggilan curl lengkapnya:

# Putaran pertama: Menghasilkan gambar dari instruksi teks murni
curl -X POST \
  "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "buat gambar anjing golden retriever sedang berlari di pantai"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

# Respons akan berisi: parts[0].inline_data.data (gambar base64)
# Serta parts[0].thought_signature

Pada permintaan putaran kedua, Anda wajib menyertakan kembali seluruh respons model dari putaran pertama (termasuk gambar dan tanda tangan/signature) ke dalam contents:

curl -X POST \
  "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "buat gambar anjing golden retriever sedang berlari di pantai"}]},
      {"role": "model", "parts": [
        {"inline_data": {"mime_type": "image/png", "data": "<base64 dari putaran pertama>"}},
        {"thought_signature": "<signature dari putaran pertama>"}
      ]},
      {"role": "user", "parts": [{"text": "ubah suasananya menjadi waktu senja"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

Perbandingan Tiga Mode Pemanggilan

Catatan Data: Gambar di atas menunjukkan perbedaan inti antara manajemen otomatis Agen vs manajemen manual API. Anda dapat membandingkan perbedaan kinerja aktual dari kedua metode pemanggilan ini secara langsung melalui platform APIYI (apiyi.com).

Mekanisme thoughtSignature untuk Pembuatan Gambar dalam Percakapan Multi-putaran Nano Banana Pro

Apa itu thoughtSignature?

thoughtSignature adalah "tanda tangan pemikiran terenkripsi" yang diperkenalkan pada seri Gemini 3. Ini adalah pengodean ringkas dari status penalaran internal model yang tidak dapat dibaca oleh manusia, namun dapat digunakan oleh model untuk memulihkan konteks dengan cepat pada putaran berikutnya. Fungsi spesifiknya:

• Mempertahankan keputusan detail: Misalnya, jika pada putaran pertama model "memutuskan" untuk menggunakan warna terang, pada putaran kedua ia akan mewarisi gaya tersebut melalui tanda tangan.
• Meningkatkan konsistensi: Karakter, latar, dan komposisi tetap stabil selama pengeditan multi-putaran.
• Menghemat token: Menghindari pengulangan perintah "pertahankan gaya asli" di dalam petunjuk.

Kapan harus menyertakan signature?

Praktik: Pola kode untuk mengelola signature secara manual

import requests
import base64
import json

API_BASE = "https://vip.apiyi.com/v1beta"
MODEL = "gemini-3-pro-image-preview"
HEADERS = {
    "x-goog-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

class NanoBananaChat:
    """Klien chat minimalis yang mengelola contents + signature secara manual"""
    def __init__(self):
        self.contents = []

    def send(self, text: str, attach_image_b64: str = None) -> dict:
        # Menyusun pesan user untuk putaran ini
        user_parts = [{"text": text}]
        if attach_image_b64:
            user_parts.append({
                "inline_data": {"mime_type": "image/png", "data": attach_image_b64}
            })
        self.contents.append({"role": "user", "parts": user_parts})

        # Mengirim permintaan
        resp = requests.post(
            f"{API_BASE}/models/{MODEL}:generateContent",
            headers=HEADERS,
            json={
                "contents": self.contents,
                "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
            }
        ).json()

        # Menambahkan respons model (termasuk signature) kembali ke contents
        model_parts = resp["candidates"][0]["content"]["parts"]
        self.contents.append({"role": "model", "parts": model_parts})
        return model_parts

# Contoh penggunaan
chat = NanoBananaChat()
parts1 = chat.send("Buatkan gambar seekor anjing golden retriever yang sedang berlari di pantai")
parts2 = chat.send("Ubah latarnya menjadi suasana senja")  # Otomatis membawa riwayat dan signature
parts3 = chat.send("Tambahkan seekor burung camar yang sedang terbang")

Saran optimasi: Saat mengakses melalui layanan proksi API APIYI (apiyi.com), platform akan meneruskan bidang thought_signature apa adanya. Pengembang hanya perlu memastikan untuk "menambahkan seluruh array model parts kembali ke contents", tanpa perlu memikirkan isi spesifik dari tanda tangan tersebut.

Skenario Praktis Pembuatan Gambar Multi-putaran Nano Banana Pro

Skenario 1: Desain Gambar Merek Progresif

Kebutuhan umum tim pemasaran: Berdasarkan satu gambar konsep produk, sesuaikan teks, skema warna, dan tata letak secara bertahap. Keunggulan API pembuatan gambar multi-putaran adalah Anda hanya perlu mendeskripsikan "perubahan inkremental" setiap kali, tanpa perlu mendeskripsikan ulang seluruh gambar dari awal:

chat = client.chats.create(model="gemini-3-pro-image-preview")

chat.send_message("Desain poster merek kopi dengan latar belakang gradasi biru tua, letakkan gambar produk di sebelah kiri")
chat.send_message("Ubah teks judul menjadi 「Awaken Your Morning」")
chat.send_message("Tambahkan placeholder kode QR di pojok kanan bawah")
chat.send_message("Buat gaya keseluruhan lebih modern, hapus hiasan renda")

Skenario 2: Pengeditan Multi-putaran Berbasis Gambar Referensi

Nano Banana Pro mendukung hingga 14 gambar referensi dalam satu permintaan. Dikombinasikan dengan percakapan multi-putaran, Anda dapat membangun alur kerja penggabungan gambar yang kuat:

# Unggah satu gambar potret + satu gambar referensi pakaian
chat.send_message([
    "Pakaikan pakaian dari gambar kedua pada orang di gambar pertama",
    {"inline_data": {"mime_type": "image/png", "data": person_b64}},
    {"inline_data": {"mime_type": "image/png", "data": outfit_b64}}
])

# Penyesuaian halus berikutnya
chat.send_message("Ubah garis leher menjadi kerah V")
chat.send_message("Ganti latar belakang menjadi abu-abu yang simpel")

Skenario 3: Pemulihan Riwayat Lintas Sesi

Jika pengguna menutup halaman di sisi depan dan membukanya kembali, dan ingin melanjutkan percakapan terakhir, Anda perlu menyimpan array contents secara persisten ke database:

import json

# Menyimpan
with open(f"sessions/{user_id}.json", "w") as f:
    json.dump(chat.get_history(), f)

# Memulihkan
with open(f"sessions/{user_id}.json") as f:
    history = json.load(f)
restored_chat = client.chats.create(
    model="gemini-3-pro-image-preview",
    history=history
)
restored_chat.send_message("Lanjutkan yang tadi, buat latar belakangnya sedikit lebih terang")

Batasan Jendela Konteks

Saran skenario: Ketika percakapan melebihi 8-10 putaran, disarankan untuk secara aktif "memotong" riwayat sebelumnya atau menggantinya dengan ringkasan LLM, jika tidak, token akan dengan cepat mendekati batas 64K. Di lingkungan produksi, pastikan untuk menambahkan penghitung token dan melakukan keputusan pemotongan di sisi klien sebelumnya.

Pertanyaan Umum

Kesimpulan

Poin utama dari API pembuatan gambar percakapan multi-putaran Nano Banana Pro:

1. Sifat Stateless: API tidak menyimpan riwayat apa pun, pemanggil harus mengelola array contents.
2. Pergantian Peran: user dan model harus bergantian secara ketat, setiap putaran parts dapat menggabungkan teks/gambar/signature.
3. Pengiriman Ulang Gambar: Gambar yang dihasilkan pada putaran sebelumnya harus dimasukkan kembali sebagai inline_data, jika tidak, model tidak akan "melihatnya".
4. Mekanisme Signature: thought_signature adalah kunci konsistensi multi-putaran, harus disertakan secara manual dalam mode REST.
5. Penyederhanaan SDK: Objek chat pada SDK Python resmi dapat mengelola semua detail di atas secara otomatis.

Bagi pengembang yang ingin segera mengimplementasikan pengalaman seperti versi web, jalur terbaik adalah menggunakan objek chat dari SDK resmi atau mode messages yang kompatibel dengan OpenAI untuk menghindari kompleksitas konstruksi REST secara manual.

Direkomendasikan untuk mengakses kemampuan pembuatan gambar percakapan multi-putaran Nano Banana Pro melalui APIYI (apiyi.com). Platform ini mendukung pemanggilan mode ganda (kolom Gemini asli dan kompatibilitas OpenAI), menyediakan kuota pengujian gratis, serta memudahkan verifikasi efek pengeditan multi-putaran dan migrasi proyek yang sudah ada dengan lancar.

📚 Referensi

1. Dokumentasi Resmi Pembuatan Gambar API Gemini: Panduan otoritatif untuk pembuatan gambar melalui percakapan multi-putaran

   • Tautan: ai.google.dev/gemini-api/docs/image-generation
   • Keterangan: Berisi spesifikasi kolom contents, serta contoh lengkap Python SDK dan REST.

2. Kartu Model Gemini 3 Pro Image Preview: Penjelasan kemampuan dan batasan model

   • Tautan: ai.google.dev/gemini-api/docs/models/gemini-3-pro-image-preview
   • Keterangan: Parameter kunci seperti jendela konteks, resolusi, jumlah gambar referensi, dan lainnya.

3. Forum Pengembang Google AI – Multi-turn Nano Banana: Contoh implementasi komunitas

   • Tautan: discuss.ai.google.dev/t/multi-turn-nano-banana-example
   • Keterangan: Praktik terbaik untuk percakapan multi-putaran yang didiskusikan oleh para pengembang.

4. Dokumentasi Vertex AI Gemini 3 Pro Image: Referensi untuk penerapan tingkat perusahaan

   • Tautan: docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image
   • Keterangan: Mencakup penggunaan tingkat lanjut seperti thought_signature dan referensi file_data.

5. Dokumentasi Integrasi APIYI Nano Banana Pro: Panduan cepat bagi pengembang di Indonesia

   • Tautan: help.apiyi.com
   • Keterangan: Berisi contoh mode ganda untuk antarmuka yang kompatibel dengan OpenAI dan antarmuka asli Gemini.

Penulis: Tim Teknis APIYI
Diskusi Teknis: Jangan ragu untuk membagikan kendala praktis yang Anda temui saat melakukan pembuatan gambar multi-putaran di kolom komentar. Untuk tips konfigurasi Nano Banana Pro lainnya, silakan kunjungi pusat dokumentasi APIYI di docs.apiyi.com.