Panduan API Nano Banana: Pembuatan dan Penyuntingan Gambar di TokenLab

API Nano Banana memiliki tiga ID model berbayar di TokenLab, dan yang termurah biayanya sekitar setengah dari harga model menengah per gambar. Kesalahan mahal yang jarang terjadi bukanlah pemilihan modelnya. Kesalahan tersebut adalah mengirim permintaan edit ke endpoint yang salah atau mencoba kembali (retry) panggilan buat (create) yang sudah membuat tugas. Panduan ini mencakup ID yang tepat, panggilan text-to-image yang berfungsi, panggilan reference-image, polling asinkron, error yang diharapkan, dan cara penetapan biaya. Harga dan daftar bidang dibaca pada 2026-10-03, jadi pastikan kembali sebelum Anda melakukan pengiriman (ship).

Poin Penting

• Kirim ID yang tepat: nano-banana-2, nano-banana-2-lite, atau nano-banana-pro. Nama tampilan (display names) bukanlah alias permintaan.
• Pekerjaan reference-image untuk Nano Banana dikirim ke POST /v1/images/generations dengan operation: "image-to-image" dan image_urls. Ini tidak dikirim ke /v1/images/edits atau /v1/chat/completions.
• Harga dasar yang kami baca pada 2026-10-03 adalah $0,0168, $0,0335, dan $0,067 per gambar untuk ID lite, standar, dan pro. Setiap model memiliki rentang harga, jadi pastikan tingkat (tier) yang tepat di Usage.
• Respons buat (create) dengan task_id, status: "pending", atau poll_url berarti Anda harus melakukan polling GET /v1/tasks/{id} hingga completed atau failed.
• Pembacaan status mengembalikan HTTP 200 bahkan ketika tugas gagal. Lakukan percabangan (branch) pada bidang status tugas, bukan kode HTTP-nya.
• Biaya akhir ada di Usage dan di billing_transaction_id, bukan di tabel harga yang disalin.

Model API Nano Banana, unit harga, dan kegunaan masing-masing

Saat kami membandingkan draf awal panduan ini dengan dokumentasi saat ini, kami menemukan tiga masalah. Draf tersebut mencantumkan model tanpa harga. Draf tersebut mengirim edit Nano Banana melalui chat completions. Draf tersebut menanyakan katalog dengan filter yang tidak digunakan oleh panduan gambar. Tabel di bawah ini memperbaiki masalah pertama. Bagian selanjutnya memperbaiki dua masalah lainnya.

ID Model	Terbaik untuk	Unit harga	Harga TokenLab (USD)	Sumber, diamati
nano-banana-2	Text-to-image dan image-to-image dengan aspect_ratio dan resolution (1k, 2k, 4k). Dirilis 2026-02-26.	per_image	$0,0335 per permintaan. Rentang $0,0225 hingga $0,0755.	API model langsung, 2026-10-03
nano-banana-2-lite	Text-to-image dan image-to-image termurah. Entri harga yang kami lihat mencakup tingkat 1k.	per_image	$0,0168 per permintaan. Min dan maks keduanya $0,0168.	API model langsung, 2026-10-03
nano-banana-pro	Text-to-image, image-to-image, dan edit gambar dengan aspect_ratio dan resolution.	per_image	$0,067 per permintaan. Rentang $0,067 hingga $0,12.	API model langsung, 2026-10-03
nano-banana	Text-to-image dengan aspect_ratio saja. Tidak ada pilihan resolution publik.	Tidak ada dalam bukti kami	Periksa halaman model atau endpoint harga	Katalog, 2026-10-02; Dokumentasi Create Image, 2026-10-03

Semua harga di atas membawa is_lock_price: true dan diperbarui pada 2026-10-02T16:53:30.068Z. Tiga detail penting sebelum Anda memilih satu:

• Tingkat resolusi mengubah harga. API langsung menunjukkan rentang untuk nano-banana-2 dan nano-banana-pro, tetapi bukti kami tidak memetakan setiap tingkat ke resolusi. Jangan berasumsi 1k adalah harga dasar. Baca entri harga untuk model Anda.
• Output teks memiliki harga tokennya sendiri. Baik nano-banana-2 maupun nano-banana-pro membawa entri native-gemini-text-output. Ini berlaku ketika outputModality adalah text. Untuk nano-banana-2, terdaftar 0,25 input dan 1,5 output. Untuk nano-banana-pro, terdaftar 1 input dan 6 output. Unitnya adalah per_token. Pastikan skalanya di GET /v1/models/:model/pricing sebelum Anda membuat anggaran di sekitarnya.
• Lite tidak mencantumkan format permintaan yang diterima. Catatan langsung untuk nano-banana-2-lite mengatakan "tidak terdaftar". Baca detailnya sebelum membangun aplikasi di atasnya.

Untuk anggaran kasar, kami mengalikan harga dasar dengan volume. Ini adalah estimasi pada harga dasar, bukan penawaran:

• 100 gambar pada nano-banana-2-lite: 100 × $0,0168 = $1,68.
• 100 gambar pada nano-banana-2: 100 × $0,0335 = $3,35.
• 100 gambar pada nano-banana-pro: 100 × $0,067 = $6,70.

Tingkat resolusi yang lebih tinggi akan menaikkan angka-angka ini.

Untuk mencantumkan model gambar saat ini sendiri, panggil endpoint yang digunakan oleh panduan pembuatan gambar. Draf sebelumnya menggunakan category=image, yang tidak didokumentasikan oleh panduan tersebut.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Untuk operasi, harga, dan siklus hidup satu model, gunakan Get a Model. Anda juga dapat menelusuri direktori Model TokenLab.

Kirim permintaan text-to-image dengan API Nano Banana

Buat kunci API di dasbor TokenLab dan ekspor:

export TOKENLAB_API_KEY="your-tokenlab-api-key"

Selalu kirim model. Referensi Create Image mengatakan API gambar tidak memilih default. Model yang hilang akan mengembalikan 400 dengan param: "model".

Permintaan ini hanya menggunakan bidang yang didaftarkan oleh dokumentasi untuk keluarga gambar Google. Kami mempertahankan resolution pada 1k karena nano-banana-2 mendokumentasikan 1k, 2k, dan 4k.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

Flag --max-time 120 sesuai dengan dokumentasi. Mereka mengatakan permintaan resolusi tinggi bisa memakan waktu hampir satu menit atau lebih, jadi atur timeout klien Anda setidaknya 120 detik. Dokumentasi mengatakan size adalah alias kompatibilitas untuk keluarga gambar Google, tetapi mereka merekomendasikan aspect_ratio secara langsung.

Keberhasilan sinkron mengembalikan gambar yang sudah selesai secara inline. Nilai placeholder di bawah ini hanya menunjukkan bentuk yang didokumentasikan:

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

Baca dalam urutan ini:

1. Jika body memiliki task_id, status: "pending", atau poll_url, Anda memiliki tugas, bukan gambar. Buka bagian polling.
2. Jika tidak, baca data[0].url. Dengan response_format: "b64_json", baca data[0].b64_json sebagai gantinya.
3. created adalah timestamp Unix. revised_prompt muncul hanya ketika model mengembalikannya, jadi jangan mewajibkannya.
4. Simpan URL gambar, ID pekerjaan Anda sendiri, model, dan request_id dari header respons.

URL gambar yang dihasilkan dapat disimpan sebagai salinan media selama 30 hari. Periksa media_retention.items untuk status setiap item dan expires_at. Salinan yang tertunda atau gagal tidak dijamin, jadi salin file ke penyimpanan Anda sendiri jika Anda membutuhkannya lebih lama. Panduan retensi data memiliki detailnya.

Edit gambar dengan URL referensi

Bayangkan tim katalog yang menginginkan foto produk yang sama dengan latar belakang studio yang bersih. Langkah yang menggoda adalah /v1/images/edits. Dokumentasi melarang hal itu. Permintaan reference-image Nano Banana diekspos pada /v1/images/generations dengan operation: "image-to-image". /v1/images/edits bukanlah jalur yang tepat untuk mereka.

Permintaan ini berasal dari panduan pembuatan gambar, dengan nano-banana-2 sebagai modelnya:

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Aturan yang kami ikuti dengan bentuk ini:

• Kirim tepat bidang referensi yang didokumentasikan. Gunakan image_url, image_urls, atau reference_image_urls dalam JSON. Jangan kirim images[] atau file_id tingkat atas. Itu milik alur edit dan ditolak di endpoint ini.
• Gunakan URL publik. Harus berupa http atau https, tanpa kredensial yang disematkan, tanpa fragmen, dan tanpa host jaringan pribadi. Hindari URL yang ditandatangani (signed URLs) yang mungkin kedaluwarsa sebelum pemrosesan dimulai.
• Gunakan multipart untuk sumber pribadi. Dokumentasi menawarkan file image multipart untuk sumber yang bersifat pribadi atau dilindungi header.
• Cocokkan resolution dengan model. Dokumentasi mengatakan nano-banana-pro mungkin menyertakannya dan nano-banana-edit harus menghilangkannya. Dokumentasi juga menamai nano-banana-edit sebagai model reference-image, tetapi ID itu tidak ada dalam katalog yang kami ambil pada 2026-10-02. Verifikasi ID apa pun terhadap /v1/models sebelum menggunakannya.

Contoh edit chat-completions dari artikel sumber sudah tidak ada. Catatan langsung mencantumkan gemini_generate_content sebagai format yang diterima untuk nano-banana-2 dan nano-banana-pro. Bukti kami tidak mendokumentasikan jalur edit gambar chat-completions.

Inpainting berbasis mask dan parameter seperti strength tidak didokumentasikan untuk Nano Banana dalam bukti kami. Periksa GET /v1/models/{model} sebelum Anda mengirimnya.

Kapan permintaan gambar menjadi tugas, dan cara melakukan polling

Panggilan buat gambar bisa sinkron atau asinkron, dan respons memberi tahu Anda yang mana. Panduan pekerjaan asinkron mencantumkan bidang pemicu: task_id, status: "pending", atau poll_url. Jika salah satu muncul, array data[] kosong dan pekerjaan masih berjalan.

Bukti kami mendokumentasikan flag permintaan async: true hanya untuk gpt-image-2 dan model gambar FLUX/BFL resmi. Ini tidak mendokumentasikannya untuk ID Nano Banana. Jangan menambahkannya ke permintaan Nano Banana. Tangani respons tugas jika kembali, dan periksa detail model jika Anda memerlukan perilaku asinkron.

Bayangkan penyegaran browser yang mengirim ulang panggilan buat setelah respons lambat. Anda sekarang membayar untuk dua generasi. Dokumentasi mengatakan sebagian besar generasi duplikat berasal dari percobaan ulang ini. Ikuti urutan ini:

1. Simpan ID segera. Simpan id atau task_id, poll_url, model, endpoint, dan ID pekerjaan Anda sendiri. id dan task_id adalah nilai yang sama.
2. Polling URL. Gunakan poll_url saat ada. Jika tidak, panggil rute tetap:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. Polling setiap 5–10 detik. Panduan mengatakan itu biasanya cukup untuk pekerjaan media yang panjang.
2. Ketahui statusnya. Statusnya adalah pending, processing, completed, dan failed. Tugas yang dibatalkan menunjukkan failed dengan cancelled: true.
3. Berhenti pada status terminal. Pada completed, baca data[].url. Hasil gambar asinkron hanya berupa URL, tidak pernah b64_json. Pada failed, baca error dan error_details.
4. Tangani timeout dengan aman. Jika panggilan buat timeout sebelum Anda melihat respons, periksa request_id dan cari tugas sebelum mencoba kembali. Jika Anda menyimpan ID tugas, lanjutkan polling. Jika polling status gagal, coba kembali polling itu dengan backoff dan jangan buat ulang.

Pembacaan status mengembalikan HTTP 200 bahkan untuk tugas yang gagal. Tugas yang gagal mungkin menyertakan error_details dengan status, type, code, message, param, dan retryable. Misalnya, error_details.status: 400 dengan param: "size" berarti permintaan perlu dikoreksi. Itu tidak berarti polling itu sendiri gagal. Mencoba kembali generasi yang gagal akan membuat tugas baru dan mungkin membuat biaya baru.

Error yang diharapkan dan apa yang harus dilakukan

Tangani error berdasarkan status HTTP dan code, jangan pernah berdasarkan message. Panduan penanganan error mengatakan pesan dapat berubah tanpa pemberitahuan. Chat Completions dan Responses menggunakan objek error gaya OpenAI, sementara format Gemini dan Anthropic menjaga bentuknya sendiri. Jangan berbagi satu parser di semua API TokenLab.

Status / code	Penyebab yang mungkin	Apa yang harus dilakukan
400, param: "model"	Tidak ada model eksplisit	Kirim model. Cantumkan ID dengan /v1/models?recommended_for=image.
400 unsupported field, atau unsupported_parameter	Bidang yang tidak didokumentasikan model, seperti resolution pada model tanpa itu	Hapus bidang atau ganti model. Jangan ulangi tanpa perubahan.
400 pada gambar referensi	Endpoint salah, atau URL pribadi atau kedaluwarsa	Gunakan /v1/images/generations dengan image_urls. Gunakan URL publik yang stabil.
401 invalid_api_key atau expired_api_key	Kunci hilang, dicabut, atau kedaluwarsa	Ganti kunci.
402 insufficient_balance atau quota_exceeded	Saldo terlalu rendah, atau kunci mencapai batasnya sendiri	Tambahkan dana, naikkan batas kunci, atau pilih model dengan harga lebih rendah.
403 model_not_allowed	Kunci tidak dapat menggunakan model itu	Perbarui daftar model kunci.
404 model_not_found	ID tidak diketahui atau tidak tersedia	Baca /v1/models dan gunakan ID saat ini.
413 payload_too_large	Permintaan atau file terlalu besar	Kurangi input.
429 rate_limit_exceeded	Terlalu banyak permintaan dalam jendela waktu	Tunggu Retry-After, lalu coba kembali.
500–504, all_channels_failed	Masalah layanan atau pasokan	Coba kembali hanya jika retryable adalah true. Hormati retry_after dan batasi upaya.

503 all_channels_failed tidak selalu berarti pemadaman. Jika retryable adalah false dan retry_after hilang, operasi tidak memiliki pasokan di tingkat Pengiriman yang dipilih. Mengulangi permintaan tidak akan membantu, jadi periksa GET /v1/models terlebih dahulu.

Polling tugas memiliki kegagalannya sendiri:

• 404 async_task_not_found: tugas kedaluwarsa atau hilang. Periksa task_id dan poll_url yang disimpan.
• 403 task_not_owned: tugas milik ruang kerja lain. Periksa ruang kerja mana yang memiliki kunci API tersebut.
• Tugas selesai tanpa URL media: perlakukan sebagai gagal. Simpan ID dan hubungi dukungan.

Saat Anda menghubungi dukungan, kirim request_id, task_id, billing_transaction_id jika ada, endpoint, model, waktu, dan nama bidang. Jangan pernah mengirim kunci, media pribadi, atau URL yang ditandatangani.

Bagaimana biaya untuk permintaan gambar ditentukan

Ketiga ID Nano Banana berbayar menggunakan unit per_image, jadi biaya utama adalah harga per_request model. Panduan penagihan menambahkan aturan di sekitarnya:

• Satu hasil, satu biaya. Setiap permintaan yang selesai dikenakan biaya satu kali, untuk opsi pengiriman yang menghasilkannya. TokenLab Verified menggunakan harga publik TokenLab. Official menggunakan lapisan harga Resmi. Auto mencoba Verified terlebih dahulu, kemudian Official.
• Tingkat menetapkan angka akhir. Rentang harga langsung ($0,0225 hingga $0,0755 untuk nano-banana-2, $0,067 hingga $0,12 untuk nano-banana-pro) menunjukkan bahwa satu harga tetap tidak mencakup setiap permintaan. Tingkat resolusi kemungkinan menjadi pendorongnya, tetapi pastikan itu dalam entri harga model.
• Tugas memesan terlebih dahulu. Tugas asinkron mungkin memesan perkiraan biayanya saat diterima. Tugas yang selesai dikenakan biaya satu kali, dan tugas yang gagal melepaskan atau mengembalikan jumlah yang tertunda. Panduan penagihan mengatakan tugas yang gagal tidak dikenakan biaya.
• Tanda hubung bukan berarti gratis. Pada halaman Model, tanda hubung di kolom harga TokenLab berarti tidak ada penawaran Verified yang tersedia saat ini.

Untuk mengonfirmasi biaya, gunakan tempat-tempat ini:

1. GET /v1/models/:model/pricing atau API Harga untuk harga saat ini.
2. Konsol, yang menunjukkan estimasi maksimum sebelum Anda mengonfirmasi pembuatan berbayar.
3. Usage untuk biaya akhir berdasarkan model.
4. billing_transaction_id dalam respons atau tugas, dan header X-Billing-Transaction-ID. Streaming dan beberapa format asli mungkin mengeksposnya hanya di header.

Jika Usage tidak menunjukkan biaya akhir atau jumlah yang dirilis setelah tugas selesai, kirim ID Permintaan dan ID tugas ke support@tokenlab.sh. Jangan salin harga dalam artikel ini ke dalam kode Anda. Panduan penagihan mengatakan untuk membaca harga saat ini ketika aplikasi Anda perlu menampilkan atau membandingkan biaya.

FAQ

ID model Nano Banana mana yang harus saya kirim untuk permintaan image-to-image?

Catatan langsung mencantumkan image-to-image untuk nano-banana-2, nano-banana-2-lite, dan nano-banana-pro. Dokumentasi juga menamai nano-banana-edit, tetapi tidak ada dalam katalog yang kami ambil pada 2026-10-02. Kirim ID dengan operation: "image-to-image" dan image_urls ke /v1/images/generations. Jalankan tes kecil pada gambar Anda sendiri, karena bukti kami tidak memiliki perbandingan kualitas.

Mengapa permintaan gambar saya mengembalikan task_id alih-alih gambar?

Panggilan buat berjalan sebagai tugas asinkron. Cari task_id, status: "pending", atau poll_url dalam respons. Simpan bidang tersebut, lalu polling poll_url atau GET /v1/tasks/{id} setiap 5–10 detik hingga statusnya completed atau failed. Jangan kirim permintaan buat kedua saat Anda menunggu.

Bisakah saya mendapatkan output base64 dari model Nano Banana?

Bidang response_format menerima url atau b64_json, dan panggilan sinkron dapat mengembalikan data[].b64_json. Hasil gambar asinkron hanya berupa URL, format apa pun yang Anda minta. Periksa detail model yang dipilih untuk memastikan model tersebut menerima b64_json, karena bidang berbeda-beda menurut model.

Apakah tugas gambar yang gagal dikenakan biaya?

Panduan penagihan mengatakan tugas yang gagal tidak dikenakan biaya, dan reservasi tertunda apa pun dirilis atau dikembalikan. Mencoba kembali generasi yang gagal membuat tugas baru dan mungkin membuat biaya baru. Konfirmasikan hasilnya di Usage menggunakan billing_transaction_id dan task_id.

Buat kunci di dasbor TokenLab, kirim permintaan text-to-image di atas dengan nano-banana-2-lite, dan periksa biayanya di Usage.