Banyak pengembang yang mengakses antarmuka penyuntingan gambar gpt-image-2 sering terjebak pada masalah yang sama: setelah membolak-balik halaman Referensi API images/edit, mereka hanya menemukan kalimat "Model gambar GPT dapat menerima maksimal 16 gambar", tetapi tidak menemukan batasan ukuran untuk satu gambar. Apakah tidak ada batasan? Atau apakah dokumentasinya yang kurang lengkap?
Jawabannya adalah: batasan itu ada dan sangat jelas—satu gambar harus berukuran kurang dari 50MB, dengan format yang didukung adalah PNG, WebP, dan JPG. Hanya saja, aturan ini tidak tertulis di tabel parameter halaman Referensi, melainkan di dokumen panduan penggunaan Image Generation yang terpisah. Informasi yang terpecah antara dua dokumen inilah yang membuat banyak orang kebingungan.
Artikel ini akan mengupas tuntas batasan unggah gambar pada API gpt-image-2: jumlah, ukuran, format, aturan mask, batasan resolusi, serta masalah praktis yang jauh lebih penting daripada batas 50MB—mengapa kami tidak menyarankan Anda benar-benar mengunggah gambar berukuran 50MB.
Batasan Unggah Gambar API gpt-image-2: Spesifikasi Resmi Lengkap
Mari kita mulai dengan kesimpulan. gpt-image-2 menerima gambar input melalui endpoint v1/images/edits, dengan batasan resmi lengkap seperti pada tabel berikut.
Tabel Ringkasan Batasan Unggah Gambar gpt-image-2
| Item Batasan | Spesifikasi Resmi | Sumber Dokumentasi |
|---|---|---|
| Maksimal gambar per permintaan | 16 gambar (Model seri GPT image) | Referensi API: images/edit |
| Ukuran per gambar | < 50MB | Panduan Penggunaan Image Generation |
| Format yang didukung | PNG, WebP, JPG | Panduan Penggunaan Image Generation |
| Metode unggah | image_url atau file_id (pilih salah satu) |
Referensi API: images/edit |
| Mask (topeng) | Format & ukuran sama dengan gambar asli, < 50MB, wajib memiliki kanal alfa | Panduan Penggunaan Image Generation |
| Jumlah hasil per permintaan n | 1-10 gambar | Referensi API: images/edit |
Artinya, secara teoritis satu permintaan edit dapat membawa hingga 16 gambar yang masing-masing mendekati 50MB. Namun, "batas teoritis" dan "cara penggunaan di lapangan" adalah dua hal yang berbeda, yang akan kita bahas lebih lanjut.
Ada satu jebakan yang perlu diperhatikan secara khusus: parameter images pada API versi baru menerima array objek, di mana setiap objek menyediakan image_url atau file_id. file_id berasal dari pra-unggah melalui Files API, yang cocok untuk skenario pustaka aset yang dapat digunakan kembali; sedangkan image_url mendukung alamat publik atau data URL base64, yang cocok untuk permintaan sekali pakai. Batasan 50MB berlaku sama untuk kedua metode tersebut.
🎯 Saran Verifikasi Cepat: Jika Anda tidak yakin apakah gambar Anda akan memicu batasan, cara paling langsung adalah mengirimkan permintaan nyata dan melihat pesan kesalahannya. Kami menyarankan untuk melakukan pengujian batas seperti ini melalui antarmuka yang kompatibel dengan OpenAI dari APIYI (apiyi.com). Panel log platform tersebut memungkinkan Anda melihat ukuran isi permintaan dan detail kesalahan secara lengkap, sehingga proses pengecekan jauh lebih intuitif dibandingkan memanggil API resmi secara langsung.
Kembali ke pertanyaan awal: mengapa halaman Referensi hanya menyebutkan 16 gambar dan tidak menuliskan ukuran filenya? Ini sebenarnya adalah keputusan desain dalam struktur dokumentasi OpenAI. Halaman Referensi images/edit disusun berdasarkan "Skema Parameter". Parameter images pada level skema hanyalah sebuah array objek, sehingga batasan jumlahnya dimasukkan ke dalam batasan array tersebut. Sementara itu, ukuran dan format file dianggap sebagai "validasi runtime" yang dikategorikan ke dalam teks naratif pada panduan Pembuatan Gambar.
Ada beberapa aturan serupa yang "tersembunyi di dalam panduan" yang sebaiknya Anda pastikan sebelum membuat fitur pengeditan gambar:
- Tiga syarat untuk mask: Harus memiliki format dan dimensi yang sama dengan gambar yang diedit, ukuran file kurang dari 50MB, dan wajib menyertakan saluran alpha—menggunakan JPG sebagai mask adalah penyebab kesalahan yang paling umum karena JPG tidak memiliki saluran alpha.
- Resolusi tidak bebas: Parameter
sizepada gpt-image-2 mendukung resolusi kustom, namun memiliki batasan ketat—sisi terpanjang tidak boleh melebihi 3840px, lebar dan tinggi harus kelipatan 16px, rasio aspek tidak boleh melebihi 3:1, dan total piksel harus berada di kisaran 655.360 hingga 8.294.400. - Gambar input dikenakan biaya: Gambar referensi dalam permintaan edit dihitung berdasarkan token input gambar. Saat
input_fidelity: highdigunakan, konsumsi token input akan meningkat secara signifikan.
Batasan Resolusi dan Parameter size gpt-image-2
| Dimensi Batasan | Aturan | Contoh |
|---|---|---|
| Sisi terpanjang | ≤ 3840px | 3840×2160 (4K landscape) bisa digunakan |
| Penyelarasan sisi | Lebar & tinggi kelipatan 16px | 1024, 1536, 2048 semuanya valid |
| Rasio aspek | ≤ 3:1 | 2048×1152 valid, 3072×1024 valid |
| Total piksel | 655.360 – 8.294.400 | Di bawah skala 768×854 akan ditolak |
| Preset umum | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | Berlaku sama untuk portrait |
Jika bisnis Anda perlu sering beralih antar resolusi, disarankan untuk membuat tabel batasan ini sebagai validasi lokal sebelum melakukan permintaan. Memblokir dimensi ilegal di sisi klien jauh lebih efisien daripada menunggu API mengembalikan kesalahan 400, karena menghemat satu kali perjalanan data. Pusat dokumentasi APIYI di apiyi.com juga telah menyusun daftar periksa validasi parameter untuk gpt-image-2 yang bisa langsung Anda gunakan sebagai referensi implementasi.
Praktik gpt-image-2: 50MB adalah batas atas, 1.5MB adalah titik ideal
Setelah mengetahui batas atas 50MB, pertanyaan yang lebih penting adalah: berapa ukuran gambar yang seharusnya dikirim dalam rekayasa teknis yang nyata? Saran kami adalah kendalikan setiap gambar di kisaran 1,5MB, dan usahakan tidak melebihi 5MB. Ini bukan sekadar tebakan, ada tiga alasan di baliknya.
Pertama adalah ekspansi base64. Jika Anda menggunakan metode data URL untuk menyematkan gambar, pengkodean base64 akan membuat ukuran file membengkak sekitar 33%—gambar asli 40MB setelah dikodekan akan mendekati 53MB. Jika ditambah dengan struktur JSON, badan permintaan (request body) bisa langsung melebihi batas. Saat 16 gambar semuanya disematkan menggunakan base64, masalah ini akan berlipat ganda 16 kali, jadi pastikan untuk menggunakan saluran unggahan file_id untuk materi berukuran besar.
Kedua adalah waktu transmisi dan dekode. Setelah melebihi 5MB, waktu unggah dan waktu dekode di sisi server akan meningkat secara non-linear. Saat terjadi fluktuasi jaringan, hal ini mudah memicu timeout dan percobaan ulang (retry), yang justru memperlambat kecepatan pembuatan gambar secara keseluruhan. Gambar berukuran sekitar 1,5MB dapat selesai diunggah dalam 1-2 detik pada koneksi internet rumah standar, menjadikannya titik keseimbangan antara stabilitas dan kualitas.
Ketiga adalah penurunan hasil kualitas gambar. gpt-image-2 akan melakukan prapemrosesan internal saat memproses gambar input. Ketika resolusi input jauh melebihi resolusi output, piksel tambahan tersebut pada dasarnya terbuang sia-sia. JPG dengan sisi terpanjang 3840px yang dikompresi di bawah 2MB hampir tidak memiliki perbedaan yang dapat dirasakan dibandingkan dengan PNG lossless 40MB dalam hal hasil pengeditan, namun biaya dan waktu yang dibutuhkan terpaut satu tingkat.
Saran Praktik Ukuran Gambar gpt-image-2
| Kondisi Gambar Asli | Penanganan yang Disarankan | Hasil yang Diharapkan |
|---|---|---|
| < 1,5MB | Unggah langsung | Kecepatan & stabilitas terbaik |
| 1,5MB – 5MB | Bisa langsung unggah, disarankan konversi ke JPG/WebP | Kecepatan dapat diterima |
| 5MB – 20MB | Kompresi ke sisi terpanjang ≤ 3840px + kualitas 85 | Kualitas hampir lossless, waktu turun drastis |
| 20MB – 50MB | Wajib kompresi, gunakan unggahan file_id | Hindari ekspansi base64 yang melebihi batas |
| > 50MB | Melebihi batas atas, wajib kompresi | Jika tidak, akan langsung error |
💡 Tips untuk skenario batch: Untuk skenario dengan konkurensi tinggi seperti penghapusan latar belakang e-commerce atau penataan gaya massal, disarankan untuk melakukan prapemrosesan kompresi "sisi terpanjang 3840px + kualitas JPG 85" menggunakan sharp atau Pillow sebelum mengunggah. Kami telah memverifikasi hal ini pada klien korporat APIYI di apiyi.com, langkah ini rata-rata dapat mengurangi waktu end-to-end dari satu permintaan edit hingga lebih dari 40%, dengan nol keluhan terkait kualitas gambar.
Panduan Cepat API gpt-image-2: Contoh Kode Pengeditan Multi-Gambar
gpt-image-2 mengikuti protokol antarmuka OpenAI standar. Berikut adalah contoh pengeditan paling sederhana yang menyertakan beberapa gambar referensi. Melalui layanan proksi API APIYI, Anda hanya perlu mengganti base_url:
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # Antarmuka terpadu APIYI
)
def to_data_url(path):
with open(path, "rb") as f:
b64 = base64.b64encode(f.read()).decode()
return f"data:image/jpeg;base64,{b64}"
result = client.images.edit(
model="gpt-image-2",
image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
prompt="Gabungkan gambar produk dengan gaya neon cyberpunk dari referensi, jaga agar subjek produk tetap sama",
input_fidelity="high", # Mempertahankan detail input dengan fidelitas tinggi, konsumsi token input lebih besar
size="2048x2048",
quality="high"
)
print(result.data[0].b64_json[:64]) # Mengembalikan gambar hasil dalam format base64
Beberapa poin parameter penting: saat input_fidelity diatur ke high, retensi detail seperti wajah dan logo meningkat secara signifikan, namun biayanya adalah peningkatan penggunaan token input gambar; quality dan size adalah dua tuas utama yang menentukan biaya output; parameter n dapat menghasilkan hingga 10 gambar dalam satu kali pemanggilan. Dari sisi penagihan, gpt-image-2 dikenakan biaya per token: input teks $5/M, input gambar $8/M (cache hit $2/M), dan output gambar $30/M. Jika dikonversi ke per gambar, level low 1024×1024 sekitar $0,006, level medium sekitar $0,05, dan level high sekitar $0,21. Sisi output selalu menjadi komponen biaya terbesar.
Perhatikan bahwa batas kecepatan resmi dibedakan berdasarkan tingkatan akun: Tier 1 hanya 5 gambar/menit, Tier 4 adalah 150 gambar/menit, dan Tier 5 adalah 250 gambar/menit. Akun baru memiliki tingkatan rendah, sehingga tugas batch mudah terkena pembatasan kecepatan. Melalui platform agregasi seperti APIYI (apiyi.com), Anda dapat melewati batasan tingkat akun tunggal, yang sangat cocok untuk lingkungan produksi yang membutuhkan konkurensi tinggi.
Perbedaan Batasan Unggahan antara gpt-image-2 dan Model Generasi Sebelumnya
Jika proyek Anda dimigrasikan dari gpt-image-1 atau DALL·E 2, Anda perlu memperhatikan beberapa perbedaan antar generasi. Perubahan terbesar terjadi antara DALL·E 2 ke seri GPT image: antarmuka edit DALL·E 2 hanya menerima satu PNG persegi dan harus kurang dari 4MB; pada seri GPT image, batasan ini dilonggarkan hingga 16 gambar, 50MB, dan tiga format. Banyak logika pra-pemrosesan "PNG + kompresi 4MB" yang tertulis di proyek lama sebenarnya dapat disederhanakan secara signifikan setelah migrasi.
Peningkatan gpt-image-2 dibandingkan gpt-image-1 terutama terlihat pada resolusi dan biaya. gpt-image-1 hanya mendukung tiga output tetap: 1024×1024, 1536×1024, dan 1024×1536; gpt-image-2 membuka resolusi kustom, mendukung output 4K dengan sisi terpanjang hingga 3840px. Dari sisi harga, input gambar gpt-image-2 turun dari $10/M menjadi $8/M, output gambar turun dari $40/M menjadi $30/M, dan menambahkan level cache hit $2/M, sehingga biaya untuk skenario gambar referensi berulang turun secara signifikan.
Perbandingan Batasan Unggahan gpt-image-2 dengan Model Terdahulu
| Item Perbandingan | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| Jumlah Gambar Input | 1 gambar | Maks 16 gambar | Maks 16 gambar |
| Batas Ukuran per Gambar | < 4MB | < 50MB | < 50MB |
| Format Input | Hanya PNG persegi | PNG/WebP/JPG | PNG/WebP/JPG |
| Resolusi Output | Gambar persegi tetap | 3 ukuran tetap | Kustom, sisi terpanjang 3840px |
| Harga Output Gambar | Penagihan per gambar | $40/M token | $30/M token (input cache $2/M) |
| input_fidelity | Tidak didukung | Didukung | Didukung, detail fidelitas tinggi lebih kuat |
Saat memigrasikan kode, Anda pada dasarnya hanya perlu mengubah parameter model, namun disarankan untuk memperbarui validasi resolusi dan strategi kompresi sesuai dengan tabel batasan di artikel ini. Jika Anda ingin memverifikasi efek migrasi sebelum mengubah kode produksi, Anda dapat menggunakan kumpulan materi yang sama di APIYI (apiyi.com) untuk memanggil kedua generasi model tersebut guna membandingkan kualitas pengeditan dan perbedaan biaya aktual secara langsung.
FAQ Pertanyaan Umum Unggah Gambar gpt-image-2
Q1: Berapa ukuran maksimal satu gambar yang bisa diunggah ke gpt-image-2?
Batas atasnya adalah 50MB, dengan dukungan format PNG, WebP, dan JPG. Batasan ini tertulis dalam panduan penggunaan Pembuatan Gambar OpenAI, bukan di tabel Referensi parameter images/edit, jadi wajar jika Anda tidak menemukannya di halaman Referensi. Untuk pengalaman terbaik, kami sarankan menjaga ukuran file di kisaran 1,5-5MB.
Q2: Bagaimana cara kerja batasan 16 gambar?
Parameter images dapat menerima maksimal 16 objek gambar, di mana setiap objek ditentukan menggunakan image_url atau file_id. Model akan menggabungkan beberapa gambar tersebut sebagai referensi bersama, yang sangat cocok untuk skenario pengeditan kombinasi seperti "gambar produk + gambar gaya + referensi komposisi". Perlu diingat bahwa 16 adalah batas input, sedangkan jumlah output dikontrol oleh parameter n dengan batas maksimal 10 gambar.
Q3: Apa penyebab umum error "invalid mask" pada masker?
Sembilan puluh persen masalahnya terletak pada saluran alpha. Masker harus memiliki format dan dimensi yang sama dengan gambar yang diedit, serta wajib menyertakan saluran alpha—karena JPG tidak mendukung saluran alpha, maka masker harus menggunakan format PNG. Area transparan berarti "izinkan untuk digambar ulang", sedangkan area tidak transparan akan tetap seperti aslinya.
Q4: Pilih unggah base64 atau file_id?
Untuk gambar kecil (< 5MB) atau permintaan sekali pakai, menggunakan data URL base64 adalah yang paling praktis. Untuk gambar besar atau aset yang perlu digunakan berulang kali, gunakan Files API untuk mengunggah terlebih dahulu guna mendapatkan file_id. Cara ini tidak hanya menghindari pembengkakan ukuran sebesar 33% akibat base64, tetapi juga memungkinkan penggunaan kembali antar permintaan. Jika ragu, Anda bisa mencoba kedua cara tersebut di konsol APIYI apiyi.com untuk membandingkan waktu respons aktual sebelum menentukan skema yang tepat.
Kesimpulan: Tiga Angka Kunci Batasan Unggah gpt-image-2
Kembali ke pertanyaan awal, batasan unggah API pengeditan gambar gpt-image-2 dapat diringkas menjadi tiga angka: 16 gambar (batas jumlah input gambar per permintaan, tertulis di Referensi), 50MB (batas ukuran per gambar, tertulis di panduan penggunaan), dan 1,5MB (ukuran ideal untuk praktik teknis). Dokumentasi yang memisahkan informasi jumlah dan ukuran di dua halaman berbeda adalah akar penyebab kebingungan "hanya melihat batas 16 gambar".
Saran implementasinya pun sederhana: lakukan kompresi sebelum mengunggah dengan batas sisi terpanjang di bawah 3840px dan kualitas JPG sekitar 85; selalu gunakan PNG dengan saluran alpha untuk masker; dan gunakan jalur file_id untuk aset berukuran besar. Jika Anda menjadikan ketiga langkah ini sebagai pra-pemrosesan standar sebelum mengirim permintaan, Anda hampir tidak akan menemui error terkait unggahan lagi.
Jika Anda perlu melakukan pemanggilan gpt-image-2 secara stabil di Indonesia, atau ingin meningkatkan batas limit ke tingkat produksi, Anda dapat mengaksesnya melalui antarmuka terpadu APIYI apiyi.com. Layanan ini kompatibel dengan penulisan asli OpenAI SDK, Anda hanya perlu mengubah satu baris base_url untuk bermigrasi.
Referensi: OpenAI API Reference: developers.openai.com/api/reference/resources/images/methods/edit
Penulis: Tim APIYI
Berfokus pada agregasi API Model Bahasa Besar AI dan praktik terbaik. Untuk ulasan model dan panduan integrasi lainnya, silakan kunjungi APIYI apiyi.com.
