Panduan proxy API gambar Gemini

Proxy API gambar Gemini adalah layanan perantara antara aplikasi Anda dan model gambar Gemini. Anda memerlukan ID model yang dapat menghasilkan gambar, format permintaan layanan tersebut, dan cara mengambil berkas hasilnya. Mengganti URL dasar klien teks saja belum membuktikan dukungan pembuatan gambar.

Alur yang didokumentasikan OmniaKey adalah buat tugas → periksa status → unduh hasil, dimulai dari POST /v1/media/tasks. Panduan ini menjelaskan seluruh alur serta perbedaannya dengan API native Google dan antarmuka yang kompatibel dengan OpenAI.

Jenis proxy apa yang diperlukan?

Proxy di sini berarti layanan API yang menangani permintaan model, autentikasi, dan respons. Proxy jaringan meneruskan lalu lintas, tetapi tidak otomatis mengubah satu format API gambar menjadi format lain. Pilih berdasarkan spesifikasi resmi layanan.

Panduan gambar Google saat ini menggunakan contoh Interactions API. Referensi GenerateContent menjelaskan kontrak yang berbeda. Jangan mencampur kolom permintaan atau pengurai responsnya, dan jangan menganggap proxy menyediakan keduanya.

Memahami gambar juga berbeda dari membuat gambar. Model yang bisa menjelaskan foto mungkin hanya menghasilkan teks. Keberhasilan panggilan teks tidak memvalidasi pembuatan atau pengeditan gambar. Label “kompatibel dengan OpenAI” juga tidak membuktikan bahwa semua metode SDK tersedia untuk jalur gambar tertentu.

Pilih model gambar yang tepat

Panduan Google membedakan ID berikut:

• Nano Banana 2.1: gemini-nano-banana-2.1, titik awal yang direkomendasikan Google untuk alur gambar umum yang baru.
• Nano Banana Pro: gemini-3-pro-image, pilihan terpisah untuk tugas visual yang lebih menuntut.
• Nano Banana 2: gemini-3.1-flash-image, generasi sebelumnya, bukan alias untuk 2.1.

Salin ID dari layanan yang akan Anda panggil. Periksa akses, dukungan pembuatan atau pengeditan, ukuran, dan satuan biaya. Untuk 2.1, OmniaKey mendokumentasikan parameters.aspect_ratio dan parameters.image_size dengan tingkat keluaran 1K, 2K, dan 4K. Kolom ini tidak dapat langsung ditukar dengan imageConfig Google atau size dan quality milik GPT Image.

Lihat halaman model Nano Banana 2.1 untuk informasi layanan terkini dan perbandingan 2.1 dengan Pro untuk memilih model.

Buat gambar melalui OmniaKey

Siapkan Bash, cURL, jq, dan kunci OmniaKey dalam variabel lingkungan lokal OMNIAKEY_API_KEY. Jalankan perintah di backend atau komputer pengembangan, bukan dengan menaruh kunci di kode browser. Prompt contoh dalam bahasa Inggris dibuat sederhana agar alur API bisa diperiksa sebelum kualitas gambar dinilai.

1. Buat dan simpan tugas

Pilih Idempotency-Key unik untuk permintaan gambar logis ini. Nilai pada contoh hanya untuk demonstrasi: ganti sekali untuk tugas baru, lalu pertahankan kunci dan isi permintaan ketika mengulang tugas yang sama. Simpan keduanya sebelum mengirim.

curl --fail-with-body --silent --show-error \
  https://api.omniakey.com/v1/media/tasks \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-image-demo-20261014-001" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "type": "image",
    "operation": "generate",
    "input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
    "parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
  }' -o task.json

Lanjutkan hanya jika cURL berhasil dan task.json memuat id. Tugas baru mengembalikan 202 Accepted; kunci dan isi yang sama mengembalikan tugas semula dengan 200. Diterima belum berarti gambar selesai. Baca siklus tugas dalam bahasa Inggris untuk detailnya.

2. Periksa ID yang sudah disimpan

Contoh Bash ini membatasi jumlah pemeriksaan. Saat batas tercapai, ID tetap tersedia untuk dilanjutkan nanti. Contoh ini tidak membatalkan tugas atau membuat tugas baru.

TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
  curl --fail-with-body --silent --show-error \
    "https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
    -o result.json || exit 1
  STATUS="$(jq -er '.status' result.json)" || exit 1
  case "$STATUS" in
    succeeded) break ;;
    failed|canceled) jq '.error' result.json; exit 1 ;;
    queued|processing) sleep 3 ;;
    *) exit 1 ;;
  esac
done

Jika pembuatan mengalami waktu habis sebelum ID diterima, ulangi dengan isi permintaan dan kunci idempotensi yang sama. Jika sudah ada ID, periksa tugas itu. Kunci baru dapat membuat tugas berbayar kedua. Pemulihan dibatasi masa penyimpanan: catatan tugas disimpan selama 24 jam sejak dibuat.

3. Unduh hanya hasil yang berhasil

jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
  "$ASSET_URL" -o generated-image

Baca mime_type untuk menentukan ekstensi berkas, lalu periksa apakah berkas dapat dibuka dan ukurannya sesuai. URL bertanda tangan memiliki masa berlaku. Selama tugas dan berkas masih tersedia, pemeriksaan ulang dapat memberikan URL baru. Unduh hasil yang ingin disimpan; tautan tersebut bukan penyimpanan permanen.

Edit menggunakan gambar referensi

Gunakan operation: "edit" dan kirim Base64 secara langsung di input.image, atau input.images untuk beberapa referensi jika didukung. Instruksi pengeditan tetap berada di input.prompt. Bentuk lengkapnya tersedia di dokumentasi API gambar dalam bahasa Inggris.

Batasnya adalah 1 MiB untuk seluruh isi permintaan, termasuk Base64. Kompres atau kecilkan referensi bila perlu. Batas unggahan API langsung Google tidak menggantikan batas proxy. Mulai dari satu gambar kecil dengan perubahan yang jelas, lalu periksa bagian yang seharusnya dipertahankan.

Mengubah prompt, referensi, model, atau parameter berarti membuat permintaan baru dan memerlukan kunci baru. Kunci lama dengan isi berbeda menghasilkan 409 idempotency_key_reused.

Cari lapisan yang mengalami kegagalan

Panduan pemecahan masalah Google menjelaskan perilaku layanan Google. Proxy menambahkan lapisan lain. Catat status HTTP, kode error, ID tugas, dan durasi tanpa data sensitif. Jangan mencatat kunci atau referensi pribadi. JSON dengan 200 saja belum membuktikan adanya gambar yang dapat dipakai.

Bandingkan biaya dan validasi integrasi

Tagihan langsung Google dan harga proxy merupakan penawaran berbeda. Sebelum menjalankan banyak tugas, periksa harga OmniaKey terkini dan satuan modelnya. Jangan memakai harga token teks untuk keluaran gambar atau menganggap langganan Gemini pribadi membayar panggilan proxy.

Ukuran yang berguna adalah total biaya yang ditagihkan ÷ jumlah gambar yang lolos penilaian. Sertakan percobaan ulang yang dikenai biaya dan hasil yang ditolak saat ditinjau. Ini rumus perencanaan, bukan hasil pengukuran atau jaminan harga termurah.

Sebelum meningkatkan volume, uji lima kasus kecil:

1. Prompt teks menghasilkan berkas gambar yang terbuka dengan format dan ukuran yang sesuai.
2. Pengeditan referensi membuat perubahan yang diminta sambil mempertahankan detail penting.
3. Pengiriman ulang kunci dan isi yang sama mengembalikan ID tugas yang sama.
4. Pemeriksaan dapat dilanjutkan melalui ID setelah waktu tunggu lokal habis.
5. Parameter tidak valid atau model tidak tersedia menghasilkan error yang jelas, bukan keberhasilan palsu.

Catat ID model, parameter, durasi, status akhir, biaya, dan hasil penilaian. Periksa ketentuan penanganan prompt serta referensi sebelum mengirim materi produksi.

Pertanyaan umum

Apakah cukup mengganti URL dasar SDK?

Hanya jika proxy mendokumentasikan endpoint, kolom, dan respons gambar yang diharapkan SDK. Uji operasi gambar itu sendiri; panggilan chat yang berhasil belum cukup.

Apakah proxy menghapus batas Gemini?

Tidak. Batas penyedia, kemampuan model, batas proxy, dan izin akun dapat berlaku bersamaan. Gateway tidak menjamin pembuatan tanpa batas atau ketersediaan di wilayah tertentu.

Model mana yang sebaiknya dicoba dahulu?

Periksa katalog saat ini, lalu nilai model gambar yang didukung melalui tugas kecil. Panduan Nano Banana 2.1 membahas perubahan model; artikel ini berfokus pada koneksi dan validasi API.

Sumber dan langkah berikutnya

Sumber utama adalah panduan gambar, referensi GenerateContent, dan pemecahan masalah Google, serta dokumentasi OmniaKey yang ditautkan. Tautan dokumentasi tersebut berbahasa Inggris. Spesifikasi diperiksa pada 14 Oktober 2026; pastikan akses model sebelum menjalankan contoh.