# Panduan proxy API gambar Gemini

> Hubungkan API gambar Gemini melalui proxy: pilih model dan format, buat tugas, unduh hasil, tangani percobaan ulang, serta hitung biaya gambar yang lolos.

- Canonical HTML: https://omniakey.com/id/blog/gemini-image-api-relay
- Markdown: https://omniakey.com/id/blog/gemini-image-api-relay.md
- Published: 2026-10-14 (updated 2026-10-14)
- Author: Kiki, COO at OmniaKey
- Language: id
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

**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 gambar pada dokumentasi OmniaKey, diperiksa pada 14 Oktober 2026, adalah **buat tugas → periksa status → unduh hasil**, dimulai dari `POST /v1/media/tasks`. Langkah di bawah 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.

|Antarmuka|Bentuk permintaan|Lokasi hasil gambar|
|-|-|-|
|Gemini GenerateContent|`/v1beta/models/MODEL:generateContent`, dengan `contents` dan kolom `generationConfig` yang didukung|Bagian gambar seperti `candidates[].content.parts[].inlineData`|
|Proxy kompatibel OpenAI|Endpoint dan skema gambar yang didokumentasikan penyedia|Data gambar atau URL sesuai format respons penyedia|
|Tugas gambar OmniaKey|`/v1/media/tasks`, dengan `model`, `type`, `operation`, `input`, `parameters`|ID tugas terlebih dahulu; `assets[]` setelah `succeeded`|

[Panduan gambar Google saat ini](https://ai.google.dev/gemini-api/docs/image-generation) menggunakan contoh **Interactions API**. [Referensi GenerateContent](https://ai.google.dev/api/generate-content) 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](https://ai.google.dev/gemini-api/docs/image-generation) 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](https://omniakey.com/id/gemini-nano-banana-2-1) untuk informasi layanan terkini dan [perbandingan 2.1 dengan Pro](https://omniakey.com/id/blog/nano-banana-2-1-vs-pro) untuk memilih model. Untuk mencoba Nano Banana 2.1 dan model Nano Banana lainnya sebelum menulis panggilan relay, buka [Generator Gambar AI](https://omniakey.com/id/ai-image-generator).

## 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.

```bash
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`. `202` belum berarti gambar selesai. Baca [siklus tugas dalam bahasa Inggris](https://docs.omniakey.com/id/media/overview) 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.

```bash
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

```bash
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](https://docs.omniakey.com/id/media/image).

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

|Gejala|Periksa|Tindakan|
|-|-|-|
|`401` / `403`|Kunci, host, format autentikasi, akses model|Perbaiki kredensial atau izin sebelum mencoba lagi|
|`400` / `404`|Endpoint, ID model, kolom, pemilik tugas|Cocokkan dengan spesifikasi; jangan menebak alias|
|`413`|Ukuran total termasuk Base64|Kecilkan gambar masukan|
|`409 idempotency_key_reused`|Kunci sama dengan isi berbeda|Gunakan isi semula untuk pemulihan atau kunci baru untuk tugas baru|
|`429`|Kuota, laju permintaan, konkurensi|Baca error, kurangi beban, dan gunakan jeda bertahap yang dibatasi bila sesuai|
|`503`|Konfigurasi atau kapasitas sementara|`worker_disabled` dan `no_available_channel` memerlukan pemeriksaan konfigurasi dan ketersediaan|
|Hanya teks atau keluaran kosong|Dukungan gambar, umpan balik keamanan, pengurai|Pada GenerateContent, periksa `promptFeedback`, `finishReason`, dan seluruh bagian respons|
|Waktu pemeriksaan habis|Apakah tugas masih berjalan?|Lanjutkan ID yang sama tanpa membuat ulang tugas|

[Panduan pemecahan masalah Google](https://ai.google.dev/gemini-api/docs/troubleshooting) 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](https://omniakey.com/id/pricing) 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](https://omniakey.com/id/models), lalu nilai model gambar yang didukung melalui tugas kecil. [Panduan Nano Banana 2.1](https://omniakey.com/id/blog/nano-banana-2-1-review) membahas perubahan model; artikel ini berfokus pada koneksi dan validasi API.

## Sumber dan langkah berikutnya

Sumber utama adalah [panduan gambar](https://ai.google.dev/gemini-api/docs/image-generation), [referensi GenerateContent](https://ai.google.dev/api/generate-content), dan [pemecahan masalah](https://ai.google.dev/gemini-api/docs/troubleshooting) Google, serta dokumentasi OmniaKey yang ditautkan. Tautan dokumentasi tersebut berbahasa Inggris. Spesifikasi diperiksa pada **14 Oktober 2026**; pastikan akses model di [halaman model Nano Banana 2.1](https://omniakey.com/id/gemini-nano-banana-2-1) sebelum menjalankan contoh.
