Nano Banana Pro API: tutorial Python, edit gambar, dan harga

Nano Banana Pro adalah gemini-3-pro-image milik Google, dan di OmniaKey Anda memanggilnya dengan satu POST /v1/media/tasks. Tiga uji 3:4 kami kembali dengan ukuran 896x1200, 1792x2400 dan 3584x4800, dan setiap kata di poster tertulis benar.

Jawaban singkat

• Model: gemini-3-pro-image adalah id model GA dari Google. Kartu model Vertex mencantumkan tanggal rilis 28 Mei 2026.
• Panggilan: kirim POST https://api.omniakey.com/v1/media/tasks dengan Idempotency-Key, polling GET /v1/media/tasks/{id} sampai statusnya succeeded, lalu unduh assets[0].url.
• Parameter: parameters.aspect_ratio dan parameters.image_size; nilai ukurannya 1K, 2K dan 4K, dengan huruf K besar.
• Batas permintaan: 1 MiB untuk seluruh body, termasuk data gambar Base64 di dalamnya.
• Harga Google: $0.134 per gambar 1K/2K dan $0.24 per gambar 4K, dari halaman harga Gemini API.
• Jumlah token kami: ketiga tugas melaporkan 1,133, 1,225 dan 2,480 token keluaran. Dengan $120 per juta token gambar, itu $0.136, $0.147 dan $0.298.
• Edit: pakai operation: "edit" dan taruh gambar sumber di input.image sebagai {data, mime_type}.

Halaman model Nano Banana Pro di OmniaKey juga menerima gemini-3-pro-image-preview, id snapshot lama, dengan harga yang sama.

Id model dan yang perlu disiapkan

Id yang ditulis di kode adalah gemini-3-pro-image. Kartu model Vertex mencantumkannya sebagai GA dengan tanggal rilis 28 Mei 2026. Model ini mendukung keluaran 1K, 2K dan 4K.

Id -preview menunjuk ke model yang sama. Tabel model gambar OmniaKey menyebut gemini-3-pro-image-preview sebagai "Same model, -preview snapshot id", dengan tarif per panggilan yang sama.

Ada dua hal yang perlu disiapkan:

1. Kunci API OmniaKey, diekspor agar bisa dibaca skrip: export OMNIAKEY_API_KEY="your-key".
2. Python 3. Skrip di bawah hanya memakai pustaka standar: urllib, json, time, uuid, base64 dan pathlib. Tidak ada SDK yang perlu dipasang.

Skrip Python

Tiga langkah: buat tugas, polling, unduh gambar. Simpan sebagai nano_banana.py dan jalankan dengan python3 nano_banana.py.

import base64
import json
import os
import time
import urllib.request
import uuid
from pathlib import Path

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}",
    "Content-Type": "application/json",
}


def call(url, payload=None, headers=None, method=None):
    body = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(url, data=body, headers=headers or HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=60) as resp:
        return resp.status, json.loads(resp.read())


def create_task(prompt, aspect_ratio="3:4", image_size="2K", image_path=None):
    body = {
        "model": "gemini-3-pro-image",
        "type": "image",
        "operation": "generate" if image_path is None else "edit",
        "input": {"prompt": prompt},
        "parameters": {"aspect_ratio": aspect_ratio, "image_size": image_size},
    }
    if image_path:
        encoded = base64.b64encode(Path(image_path).read_bytes()).decode("utf-8")
        body["input"]["image"] = {"data": encoded, "mime_type": "image/png"}
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    status, task = call(API, body, headers, "POST")
    print("created", task["id"], "HTTP", status)
    return task


def wait(task_id, interval=3, timeout=300):
    deadline = time.time() + timeout
    while time.time() < deadline:
        _, task = call(f"{API}/{task_id}")
        print(task["status"], task["progress"]["percent"])
        if task["status"] in ("succeeded", "failed", "canceled"):
            return task
        time.sleep(interval)
    # A timeout is not a failure: keep the task id and poll it again.
    raise TimeoutError(f"task {task_id} is still running")


def download(task, out_path):
    asset = task["assets"][0]
    with urllib.request.urlopen(asset["url"], timeout=120) as resp:
        Path(out_path).write_bytes(resp.read())
    print("saved", out_path, asset["mime_type"], asset["byte_size"], "bytes")


if __name__ == "__main__":
    task = create_task(
        "A vintage travel poster for the Night Train from Zürich to Milano, "
        "departing 21:40 from platform 7. A steam train crosses a stone arch "
        "bridge below snowy mountains under a deep blue night sky, with a cream "
        "border. Spell every word exactly as written.",
        aspect_ratio="3:4",
        image_size="2K",
    )
    task = wait(task["id"])
    if task["status"] != "succeeded":
        raise SystemExit(f"{task['status']}: {task.get('error')}")
    download(task, "night-train.jpg")

image_size menerima 1K, 2K atau 4K. Panduan gambar Google tegas: "You must use an uppercase 'K' … Lowercase parameters (e.g., 1k) will be rejected." Kirim 2K, bukan 2k.

Idempotency-Key wajib. UUID baru untuk setiap permintaan adalah aturan paling sederhana; pakai ulang kunci hanya saat mengirim ulang body yang benar-benar sama. OmniaKey mengembalikan tugas asli dengan HTTP 200 alih-alih menagih dua kali, dan menjawab 409 jika kunci yang sama datang dengan body berbeda.

Panggilan pembuatan mengembalikan 202 dengan sebuah id. Dokumentasi tugas media OmniaKey menjelaskan seluruh alurnya; tugas yang selesai membawa kolom berikut:

{
  "id": "task_AbMRVqzSnVh0VwBj0S7NuMUxy5sZtfHP",
  "status": "succeeded",
  "progress": {"percent": 100, "stage": "completed"},
  "usage": {"total_tokens": 1133},
  "assets": [
    {
      "kind": "image",
      "mime_type": "…",
      "url": "https://…signed-url…"
    }
  ]
}

Baca assets[0].url lalu unduh saat itu juga: tautan bertanda tangan berlaku sekitar satu jam, dan catatan tugas tersimpan 24 jam. Kolom mime_type memberi tahu formatnya; model Gemini biasanya mengembalikan JPEG.

Skrip yang sama pada 1:1 dan 2K, dengan papan nama berbahasa Mandarin sebagai prompt, menghasilkan ini:

Mengedit gambar yang sudah ada

Tulis operation: "edit" dan kirim gambar sumber di input.image sebagai {data, mime_type}. Skrip di atas sudah melakukannya begitu Anda memberi image_path:

task = create_task(
    "Hang this poster in a thin black frame on a warm white wall, with a brass "
    "picture light above it, a low wooden cabinet below and a trailing plant on "
    "the right. Keep the poster exactly as it is.",
    aspect_ratio="1:1",
    image_size="2K",
    image_path="night-train-2k.png",
)

Body yang dikirim tampak seperti ini:

{
  "model": "gemini-3-pro-image",
  "type": "image",
  "operation": "edit",
  "input": {
    "prompt": "Hang this poster in a thin black frame on a warm white wall…",
    "image": {"data": "…base64…", "mime_type": "image/png"}
  },
  "parameters": {"aspect_ratio": "1:1", "image_size": "2K"}
}

Sumber contohnya PNG, jadi skrip menulis image/png; ganti label itu untuk JPEG. Untuk beberapa referensi, pakai input.images dan beri setiap entri bentuk {data, mime_type} yang sama. Panduan Google menetapkan batas 14 gambar referensi; untuk gemini-3-pro-image pembagiannya 6 gambar objek, 5 gambar karakter dan 3 referensi gaya.

Jaga body di bawah 1 MiB. Base64 membuat file sekitar sepertiga lebih besar, jadi kecilkan atau kompres sumber sebelum mengodekannya. Edit kami memakai poster 2K dan mempertahankan setiap kata serta tata letaknya:

1K, 2K dan 4K: apa yang didapat

Kami menjalankan prompt poster 3:4 yang sama pada ketiga ukuran. Jumlah pikselnya sama persis dengan tabel Google untuk 3:4: 896x1200 di 1K, 1792x2400 di 2K dan 3584x4800 di 4K. Teks poster benar di semua ukuran.

Yang berubah dengan ukuran adalah detailnya, bukan ejaannya:

• 1K: bagian depan kereta berdesakan: lampu, roda dan batang penggerak berdiri rapat.
• 2K: desa dan dua menaranya muncul di lereng kanan, cerobong mengeluarkan benang asap pucat, dan jembatan memperlihatkan tujuh lengkung.
• 4K: ketiga gerbong dan tender terpisah, dan pasangan batunya menunjukkan sambungan dengan ketebalan berbeda. Mesin di bawah lokomotif masih disederhanakan.

Kecepatannya naik seiring ukuran: 28.4 dtk, 48.2 dtk dan 66.9 dtk. Setiap ukuran kami jalankan sekali, jadi baca detik itu sebagai satu kali jalan.

Google menagih keluaran gambar $120 per juta token, dan tabelnya memberi 1,120 token untuk 1K maupun 2K serta 2,000 token untuk 4K. Dari situ muncul perkiraan Google sendiri:

1,120 × $120 ÷ 1,000,000 = $0.134 per 1K image
1,120 × $120 ÷ 1,000,000 = $0.134 per 2K image
2,000 × $120 ÷ 1,000,000 = $0.24  per 4K image

Tugas kami melaporkan token lebih banyak daripada contoh Google. Berikut aritmetika yang sama dengan angka kami:

1,133 × $120 ÷ 1,000,000 = $0.136 per 1K image
1,225 × $120 ÷ 1,000,000 = $0.147 per 2K image
2,480 × $120 ÷ 1,000,000 = $0.298 per 4K image

OmniaKey menagih panggilan gambar dengan tarif tetap, bukan per token, jadi biayanya tidak bergerak mengikuti hitungan itu; tarif per panggilan saat ini ada di halaman model, dan tugas yang gagal dikembalikan dananya. Perkiraan Google dengan tarif token untuk ketiga gambar yang sama adalah $0.134, $0.134 dan $0.24.

Kesalahan yang akan Anda temui

Kegagalan di sini hampir selalu bermuara pada nama kolom atau ukuran file, bukan pada model. Berikut yang dicantumkan dokumentasi media OmniaKey untuk endpoint ini:

Tugas failed bukan kesalahan HTTP: panggilan pembuatan sudah berhasil, jadi polling tugasnya dan baca objek error. Tugas yang gagal dan dibatalkan dikembalikan dananya otomatis.

Sumber resolusi penuh yang dikirim sebagai Base64 bisa mendorong body melewati 1 MiB. Kecilkan dulu, lalu periksa panjang setelah pengodean, bukan hanya ukuran file.

Panduan Google menolak 1k huruf kecil. Pakai 1K, 2K atau 4K.

Dokumentasi gambar OmniaKey juga menolak size dan mime_type tingkat atas pada model Gemini, karena keduanya bukan parameter Gemini. Pakai parameters.aspect_ratio dan parameters.image_size, lalu baca format keluaran dari kolom mime_type pada respons.

Pertanyaan umum

Apa id model API Nano Banana Pro?

gemini-3-pro-image. Kartu model Vertex Google mencantumkannya sebagai GA dengan tanggal rilis 28 Mei 2026, dan OmniaKey menerima id yang sama. Id lama gemini-3-pro-image-preview masih berfungsi di OmniaKey dan menunjuk ke model yang sama.

Berapa harga satu gambar Nano Banana Pro?

Google memperkirakan $0.134 untuk gambar 1K atau 2K dan $0.24 untuk gambar 4K, pada tarif $120 per juta token gambar. Tugas kami melaporkan 1,133, 1,225 dan 2,480 token, yang berarti $0.136, $0.147 dan $0.298 pada tarif itu. Halaman model OmniaKey mencantumkan tarif per panggilannya sendiri.

Bisakah Nano Banana Pro menulis teks Mandarin?

Bisa. Papan nama 2K kami kembali dengan tiga baris Mandarin yang benar — 同福客栈, 住宿 餐饮 茶水 dan 010-6789 4321 — termasuk 11 angka dan tanda hubungnya.

Sebaiknya minta 1K, 2K atau 4K?

Untuk poster seperti punya kami, 2K adalah titik tengah yang berguna. Ketiga ukuran menulis poster kami dengan benar, jadi 4K membeli detail lebih halus — gerbong terpisah dan sambungan bata — bukan teks yang lebih baik. Pakai 1K untuk draf yang cukup dengan 896x1200.

Kenapa edit saya mengembalikan 400 invalid_request?

Penyebab umumnya body lebih dari 1 MiB, sumber di kolom yang salah, atau model Gemini menerima size atau mime_type tingkat atas. Taruh gambar di input.image sebagai {data, mime_type}, jaga body hasil pengodean di bawah 1 MiB, dan pakai aspect_ratio serta image_size.

Sumber yang diperiksa

• Google Cloud: kartu model Gemini 3 Pro Image — diperiksa 3 November 2026.
• Google: panduan pembuatan gambar Gemini API — diperiksa 3 November 2026.
• Google: harga Gemini API — diperiksa 3 November 2026.
• Google: pengumuman Nano Banana Pro — diperiksa 3 November 2026.

Catatan pembaruan

• 2026-11-03: versi pertama; lima panggilan uji lewat OmniaKey pada hari itu.