DEV Community

Cover image for Cara Menggunakan API gpt-image-2
Walse
Walse

Posted on • Originally published at apidog.com

Cara Menggunakan API gpt-image-2

API gpt-image-2 adalah endpoint pembuatan gambar terbaru dari OpenAI, dirilis bersama ChatGPT Images 2.0 pada 21 April 2026. Jika Anda sudah pernah menggunakan API chat atau embeddings OpenAI, menambahkan pembuatan gambar cukup menambah satu permintaan baru, kunci API dengan cakupan yang benar, dan waktu setup sekitar sepuluh menit.

Coba Apidog hari ini

Panduan berikut akan fokus pada implementasi API: autentikasi, parameter permintaan, contoh kode dalam tiga bahasa, mode thinking, pembuatan batch, penanganan respons, kode error, batas laju, dan workflow pengujian agar Anda tidak membuang kredit akibat prompt error. Untuk gambaran produk dan apa yang baru di ChatGPT Images 2.0, lihat uraian ChatGPT Images 2.0.

Setelah mengikuti panduan ini, Anda akan memiliki API call yang berfungsi, koleksi Apidog reusable untuk iterasi, dan estimasi biaya tiap parameter.

Prasyarat

Siapkan empat hal berikut sebelum request pertama Anda:

  • Akun OpenAI dengan akses API (terpisah dari akun ChatGPT Plus; langganan ChatGPT tidak termasuk kredit API).
  • Tingkat penggunaan berbayar. gpt-image-2 tersedia mulai Tier 1 ke atas. Akun baru mulai dari tingkat Gratis, tambahkan pembayaran untuk mengakses endpoint gambar.
  • Kunci API dengan scope images:write. Untuk produksi, gunakan kunci scoped project, bukan user.
  • Alat pengujian untuk preview gambar. curl di terminal cukup untuk tes awal; setelah itu, gunakan API client khusus.

Set ENV sekali agar setiap contoh berikut bisa langsung dijalankan:

export OPENAI_API_KEY="sk-proj-..."

Endpoint dan Autentikasi

Endpoint tetap sama dengan model sebelumnya:

POST https://api.openai.com/v1/images/generations

Autentikasi memakai bearer token di header Authorization. Badan request berupa JSON dengan model id, prompt, dan parameter output.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A sharp product hero image for an API testing platform, dark background",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

Respons sukses menghasilkan objek JSON dengan array data berisi gambar. Gagal akan return error envelope OpenAI standar (code & message); lihat tabel error di bawah.

Parameter Permintaan

Setiap field mempengaruhi biaya dan output. Berikut peta parameter gpt-image-2:

Parameter Tipe Nilai Catatan
model string gpt-image-2 Wajib.
prompt string Hingga 32.000 karakter Wajib. Prompt panjang = lebih banyak token input.
size string 1024x1024, 1024x1536, 1536x1024, 2000x1000, 1000x2000, 2000x667, 667x2000 Pengaruh token output.
quality string standard, high high 2× lebih mahal, lebih baik untuk teks halus/elemen UI.
n integer 1–10 Batch request; satu gaya untuk semua.
thinking string off, low, medium, high Budget reasoning sebelum render.
response_format string url, b64_json URL expired dalam 1 jam.
user string Bebas Untuk abuse detection; hash-kan user id.
background string auto, transparent, opaque Transparent output sebagai PNG dengan alpha.
seed integer Int32 apapun Seed sama + prompt sama → output mirip (tidak identik).

Parameter paling pengaruh biaya: size, quality, thinking. Gambar 2000px high + thinking: "high" bisa 4–5× biaya 1024x1024 standard.

Contoh Python

SDK resmi (openai>=1.50.0) sudah support gpt-image-2:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt=(
        "A minimalist diagram of an OAuth 2.1 authorization code flow with PKCE. "
        "Five boxes labeled in English: User, Client, Auth Server, Resource Server, Token. "
        "Sharp sans-serif text, off-white background, teal accent arrows."
    ),
    size="1536x1024",
    quality="high",
    n=2,
    thinking="medium",
    response_format="b64_json",
)

out_dir = Path("out")
out_dir.mkdir(exist_ok=True)

for i, image in enumerate(response.data):
    png_bytes = base64.b64decode(image.b64_json)
    (out_dir / f"oauth_{i}.png").write_bytes(png_bytes)

print(f"Generated {len(response.data)} images into {out_dir.resolve()}")
  • response.data selalu list, meski n=1; lakukan iterasi.
  • b64_json cocok untuk skrip lokal; url lebih baik untuk pipeline CDN/S3.

Contoh Node.js / TypeScript

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt:
    "Dashboard UI mockup for a REST client, sentence-case labels, latency sparkline in the top-right, cool grey palette.",
  size: "1536x1024",
  quality: "high",
  n: 4,
  thinking: "medium",
  response_format: "b64_json",
});

await Promise.all(
  response.data.map(async (image, i) => {
    if (!image.b64_json) return;
    await fs.writeFile(`dash_${i}.png`, Buffer.from(image.b64_json, "base64"));
  }),
);

console.log(`Saved ${response.data.length} images`);

Gunakan SDK resmi, bukan fetch mentah, kecuali ada alasan khusus. SDK meng-handle retry, idempotency, streaming, dan tracking perubahan skema antar model version.

Mode thinking: Kapan Digunakan

thinking mengatur alokasi komputasi untuk perencanaan tata letak sebelum render:

  • off: tanpa reasoning; tercepat dan termurah, untuk prompt bebas.
  • low: planning ringan. Default untuk foto produk/gambar hero.
  • medium: planning berat. Untuk diagram, infografis, slide, dsb.
  • high: reasoning maksimum. Untuk layout multibahasa/diagram teknis kompleks; lebih mahal dan lambat.

Tips: prompt dengan angka/label/posisi → naikkan level. Prompt "vibe"/scene → turunkan.

thinking menambah token reasoning ke biaya. Cek harga OpenAI; estimasi 1.2–2× dari basic jika pakai medium atau high.

Pembuatan Batch

Set n > 1 untuk return banyak gambar dalam satu response (gaya dan komposisi seragam). Berbeda dengan n request paralel—batch output lebih koheren, cocok untuk workflow desain.

response = client.images.generate(
    model="gpt-image-2",
    prompt="Four different hero illustrations for an API documentation landing page, shared color palette, shared line weight.",
    size="1536x1024",
    quality="high",
    n=4,
    thinking="low",
)

Biaya tetap per image: n=4 = 4× n=1. Keuntungan utama: konsistensi, bukan throughput.

Format & Penyimpanan Respons

  • b64_json: gambar langsung direspons. Mudah untuk skrip, payload cepat besar (PNG 2000px bisa >3MB).
  • url: gambar di CDN OpenAI (1 jam), Anda unduh manual. Ideal untuk serverless/pipeline storage sendiri.

Untuk produksi: segera unduh & simpan gambar ke storage sendiri (S3, R2, Cloudflare Images). Jangan kirim URL OpenAI ke end-user; expired dalam sejam.

Error Handling & Rate Limit

gpt-image-2 return error standar OpenAI. Tabel error umum:

HTTP code Penyebab Perbaikan
400 invalid_request_error Ukuran/prompt tidak valid Periksa parameter, potong prompt.
401 invalid_api_key Kunci salah/hilang Re-export OPENAI_API_KEY.
403 insufficient_quota Kredit habis/Free tier Tambah pembayaran/verifikasi tier.
429 rate_limit_exceeded Request/minute terlalu banyak Backoff dengan jitter, cek Retry-After.
429 image_generation_user_error Konten prompt ditolak Ubah kata prompt.
500 server_error Masalah server OpenAI Retry 2x dengan exponential backoff.
503 overloaded Lonjakan traffic regional Tunggu & retry.

Rate limit berbasis tier. Tier 1: ~50 request/menit; lebih tinggi = lebih banyak. Pantau x-ratelimit-remaining-requests & x-ratelimit-remaining-tokens di setiap response, dan throttle sebelum limit habis.

Retry hanya untuk error 5xx/429 (bukan error 400/401/429 konten):

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def generate_with_retry(prompt: str, tries: int = 3):
    delay = 1.0
    for attempt in range(tries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
            )
        except RateLimitError:
            time.sleep(delay)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < tries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("gpt-image-2 retries exhausted")

Tidak perlu retry error 400/401/429 konten, karena hanya membuang kredit.

Menguji API dengan Apidog

Iterasi prompt di terminal lambat: tidak bisa preview, susah bandingkan parameter, tidak bisa versioning prompt yang bagus. Pakai API client khusus untuk workflow yang lebih produktif.

Apidog mendukung gpt-image-2 sebagai first-class request. Alur kerja:

  1. Buat request baru di koleksi OpenAI, POST ke https://api.openai.com/v1/images/generations.
  2. Tambah header Authorization: Bearer {{OPENAI_API_KEY}}; set OPENAI_API_KEY di environment variable.
  3. Paste JSON body prompt Anda; Apidog validasi ke OpenAPI dan deteksi error sebelum request dikirim.
  4. Klik Kirim. Gambar dirender inline; simpan yang bagus, tandai yang gagal, fork request untuk varian baru.
  5. Simpan environment untuk thinking: off, medium, high dan bandingkan output prompt yang sama.

Fitur perbandingan request Apidog sangat membantu: ubah satu parameter, lihat gambar before/after side-by-side, simpan prompt terbaik untuk tim. Workflow seperti ini tidak bisa dilakukan dari terminal.

Jika Anda biasa pakai klien HTTP lain atau workspace Postman yang rusak, Unduh Apidog dan masukkan kunci OpenAI Anda; setup kurang dari 5 menit. Untuk evaluasi alternatif, baca juga panduan pengujian API tanpa Postman dan overview ekstensi Apidog VS Code.

Kesalahan Umum

  • Pakai quality: "standard" untuk prompt penuh teks: Huruf kecil sering rusak. Untuk label/UI, langsung gunakan high.
  • Prompt terlalu panjang: 32k karakter itu limit, bukan target. Model mulai mengabaikan instruksi awal jika terlalu panjang. Usahakan <500 kata dan gunakan thinking untuk constraint kompleks.
  • Ekspektasi seed = output sama persis: Seed hanya mengurangi variansi, tidak mengunci output. Untuk re-use, cache langsung file binernya.
  • Share URL OpenAI ke user: URL expired 1 jam. Selalu salin ke storage sendiri sebelum didistribusikan.
  • Loop endpoint terlalu rapat: Render gambar lambat. Paralelkan worker & patuhi rate limit header; loop sekuensial cepat timeout.

FAQ

Bedanya gpt-image-2 dengan gpt-image-1 di API? Endpoint & autentikasi sama. Parameter baru: thinking, size sampai 2000px, n sampai 10 (gaya sama). SDK lama tetap jalan, cukup ganti model id dan tambah parameter baru sesuai kebutuhan. Lihat perbedaan ChatGPT Images 2.0 untuk detail.

Cara tercepat prototipe integrasi gpt-image-2? Buat request di Apidog, simpan dua environment (standard vs thinking), iterasi prompt tanpa coding. Export request ke curl/SDK jika sudah final.

Apakah API support image edit/inpainting? Endpoint edit/variasi mengikuti pattern generasi lama, tinggal pakai model id baru. Cek referensi model gpt-image-2 untuk skema terkini; input/mask documented di sana.

Boleh untuk output komersial? Ya, sesuai kebijakan OpenAI. Anda punya hak atas gambar; OpenAI berhak gunakan input/output untuk abuse monitoring. Karakter/merek/figur publik tetap kena guardrail.

Estimasi biaya produksi? Sekitar $0.21/gambar berkualitas tinggi 1024×1024 (mode standard). 10.000 gambar/bulan = $2.100, belum termasuk thinking mode (tambah 20–80%). Bandingkan dengan alternatif self-host seperti GLM 5V Turbo dan Qwen 3.5 Omni jika butuh murah.

Ada alternatif murah dengan kualitas teks serupa? Belum ada yang setara untuk teks multibahasa. Open-weight model mulai mendekati, tapi masih tertinggal di skrip CJK/Indic.

Top comments (0)