Cara Menggunakan API gpt-image-2

API gpt-image-2 adalah endpoint pembuatan gambar baru OpenAI, yang dirilis bersama ChatGPT Images 2.0 pada tanggal 21 April 2026. Jika Anda sudah memanggil API chat atau embeddings OpenAI, menambahkan pembuatan gambar hanya membutuhkan satu bentuk permintaan baru, kunci API dengan cakupan yang tepat, dan sekitar sepuluh menit.

Panduan ini secara ketat tentang API: autentikasi, parameter permintaan, contoh kode dalam tiga bahasa, mode berpikir, pembuatan batch, penanganan respons, kode kesalahan, batas laju, dan alur kerja pengujian yang mencegah Anda menghabiskan kredit karena prompt yang rusak. Untuk gambaran umum tingkat produk tentang apa yang baru di ChatGPT Images 2.0, lihat uraian ChatGPT Images 2.0 kami.

Pada akhirnya, Anda akan memiliki panggilan yang berfungsi, koleksi Apidog yang dapat digunakan kembali untuk iterasi, dan gambaran jelas tentang biaya setiap parameter.

Prasyarat

Sebelum permintaan pertama Anda, Anda membutuhkan empat hal:

• Akun OpenAI dengan akses API. Akun pengembang terpisah dari ChatGPT Plus; langganan ChatGPT tidak termasuk kredit API.
• Tingkat penggunaan yang dapat ditagih. gpt-image-2 tersedia di Tingkat 1 dan di atasnya. Akun baru dimulai dengan tingkat Gratis dan harus menambahkan pembayaran sebelum endpoint gambar terbuka.
• Kunci API dengan cakupan images:write. Kunci lingkup proyek direkomendasikan daripada kunci lingkup pengguna untuk produksi.
• Alat pengujian yang mempratinjau respons gambar. Terminal curl berfungsi untuk permintaan pertama; setelah itu, gunakan klien API sungguhan. Lebih lanjut tentang itu di bawah.

Atur kunci sekali di shell Anda agar setiap contoh dalam panduan ini berjalan tanpa pengeditan:

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

Endpoint dan autentikasi

gpt-image-2 menggunakan endpoint pembuatan gambar yang sama dengan model sebelumnya:

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

Autentikasi adalah token bearer di header Authorization. Setiap permintaan juga membawa badan JSON dengan ID model, prompt, dan parameter keluaran.

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"
  }'

Jika panggilan berhasil, Anda akan mendapatkan objek JSON dengan array data berisi gambar. Kegagalan akan mengembalikan envelop kesalahan OpenAI standar dengan code dan message yang dapat dibaca manusia; tabel kesalahan di panduan ini nanti akan membahas yang umum.

Parameter permintaan

Setiap bidang dalam badan permintaan mengubah apa yang Anda bayar dan apa yang Anda dapatkan. Berikut adalah peta parameter lengkap untuk gpt-image-2.

Tiga parameter yang paling mengubah biaya adalah size, quality, dan thinking. Gambar berkualitas high selebar 2000 piksel dengan thinking: "high" dapat berharga 4–5× dari render 1024x1024 standard dasar.

Contoh Python

SDK resmi (openai>=1.50.0) menambahkan dukungan native untuk 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()}")

Dua hal yang patut diperhatikan:

• response.data adalah daftar bahkan ketika n=1. Selalu lakukan iterasi.
• b64_json lebih mudah untuk skrip lokal; url lebih baik ketika Anda meneruskan gambar ke CDN atau unggahan S3, karena Anda melewati siklus decode-lalu-reencode.

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 daripada fetch mentah kecuali Anda memiliki alasan untuk tidak melakukannya. SDK menangani percobaan ulang, header idempotensi, dan streaming, serta melacak perubahan skema yang merusak antara revisi model.

Mode berpikir: kapan menggunakannya

thinking mengontrol seberapa banyak komputasi yang dihabiskan model untuk merencanakan tata letak sebelum merender. Empat nilai, kira-kira:

• off: tanpa penalaran. Tercepat, termurah, terbaik untuk prompt kreatif longgar di mana komposisi tidak harus tepat.
• low: perencanaan ringan. Default yang baik untuk foto produk dan gambar hero.
• medium: perencanaan lebih berat. Pilihan tepat untuk diagram, infografis, slide, dan apa pun dengan elemen yang dihitung ("empat panel", "tiga panah").
• high: penalaran maksimum. Hanya menguntungkan untuk tata letak multibahasa yang kompleks atau diagram teknis yang ketat; harapkan latensi dan biaya yang jauh lebih tinggi.

Aturan praktis: jika prompt berisi angka, label, atau batasan posisi, naikkan satu tingkat. Jika hanya mengatakan "adegan yang nyaman", turunkan satu tingkat.

Mode berpikir menambahkan token penalaran ke tagihan di atas token output gambar. Halaman harga OpenAI mencantumkan tarif per-token saat ini; anggarkan 1.2–2× biaya gambar dasar Anda saat medium atau high diaktifkan.

Pembuatan batch

Mengatur n > 1 mengembalikan beberapa gambar dalam satu respons yang berbagi komposisi dan gaya. Ini tidak sama dengan memanggil endpoint n kali secara paralel; itu akan memberi Anda empat gambar yang tidak terkait. Output batch bersifat koheren, yang sesuai dengan cara tim desain beriterasi.

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",
)

Anda membayar per gambar, jadi n=4 kira-kira berharga 4× n=1. Keuntungannya adalah konsistensi, bukan throughput.

Format dan penyimpanan respons

Dua format, dua kasus penggunaan:

• b64_json: gambar disertakan dalam respons. Mudah untuk skrip. Payload respons menjadi besar dengan cepat; PNG berkualitas tinggi dengan lebar 2000 piksel dapat mendorong ukuran respons melewati 3 MB.
• url: gambar berada di CDN OpenAI selama satu jam, dan Anda mengunduhnya sendiri. Lebih baik untuk fungsi tanpa server dengan batasan ukuran respons dan untuk pipeline yang meneruskan gambar ke penyimpanan Anda sendiri.

Untuk produksi, unduh URL dan dorong ke bucket S3, R2, atau Cloudflare Images Anda sendiri segera. Jangan kirim URL OpenAI ke pengguna akhir; URL tersebut kedaluwarsa.

Penanganan kesalahan dan batas laju

gpt-image-2 mengembalikan bentuk kesalahan OpenAI standar. Berikut adalah yang akan Anda temui:

Batas laju pada gpt-image-2 berbasis tingkat. Pada Tingkat 1 Anda mulai sekitar 50 permintaan per menit; tingkat yang lebih tinggi akan meningkat. Selalu baca header x-ratelimit-remaining-requests dan x-ratelimit-remaining-tokens pada setiap respons dan batasi sebelum Anda mencapai batas.

Kesalahan yang dapat dicoba ulang dalam produksi:

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")

Jangan coba lagi kesalahan 400-an, 401-an, atau 429-an kebijakan konten; itu gagal karena suatu alasan dan mencoba lagi hanya membuang-buang kredit.

Menguji API dengan Apidog

Iterasi pada prompt pembuatan gambar dari terminal lambat: Anda tidak dapat melihat hasilnya, tidak dapat membedakan perubahan parameter, dan tidak dapat membuat versi prompt yang baik. Klien API yang dibuat khusus memecahkan ketiga masalah tersebut.

Apidog memperlakukan endpoint gpt-image-2 sebagai permintaan kelas satu. Alur kerja tipikal:

1. Buat permintaan baru di koleksi OpenAI Anda, metode POST, URL https://api.openai.com/v1/images/generations.
2. Tambahkan Authorization: Bearer {{OPENAI_API_KEY}} sebagai header; atur OPENAI_API_KEY dalam variabel lingkungan sehingga tidak pernah ada dalam kode sumber.
3. Tempel badan JSON dengan prompt Anda; Apidog memvalidasi terhadap spesifikasi OpenAPI dan menampilkan ketidakcocokan tipe sebelum Anda mengirim.
4. Tekan Kirim. Respons gambar akan dirender secara inline; simpan yang bagus, tandai yang buruk, buat permintaan fork untuk varian.
5. Simpan lingkungan untuk thinking: off, thinking: medium, dan thinking: high untuk membandingkan prompt yang sama di seluruh tingkat penalaran.

Perbandingan permintaan Apidog adalah bagian terpenting di sini. Anda mengubah satu parameter; Anda melihat gambar sebelum dan sesudah secara berdampingan; Anda menyimpan pemenang ke pustaka prompt yang dibagikan seluruh tim Anda. Ini adalah alur kerja yang tidak dapat diberikan oleh terminal kepada Anda.

Jika Anda berasal dari klien HTTP generik atau ruang kerja Postman yang rusak, Unduh Apidog dan arahkan ke kunci OpenAI Anda; pengaturan memakan waktu kurang dari lima menit. Tim yang mengevaluasi alternatif juga dapat membaca panduan pengujian API tanpa Postman dan gambaran umum ekstensi Apidog VS Code kami.

Kesalahan umum

Beberapa kesalahan menghabiskan kredit dan waktu di minggu pertama dengan gpt-image-2.

• Menggunakan quality: "standard" untuk prompt yang banyak teksnya. Kualitas standar merusak teks kecil. Langsung gunakan high ketika label, ikon, atau salinan UI penting.
• Prompt yang berlebihan. 32k karakter adalah batas atas, bukan target. Setelah beberapa ratus token, model mulai mengabaikan instruksi sebelumnya. Jaga agar prompt di bawah 500 kata dan gunakan thinking untuk menerapkan batasan kompleks.
• Mengharapkan reproduksibilitas dari seed. Seed mengurangi varians tetapi tidak mengunci output. Jika Anda membutuhkan gambar yang persis sama, cache biner; jangan buat ulang.
• Mengirimkan URL OpenAI. URL tersebut kedaluwarsa dalam satu jam. Selalu salin ke penyimpanan Anda sendiri sebelum melayani downstream.
• Memanggil endpoint dalam loop yang ketat. Pembuatan gambar lambat. Paralelkan di seluruh pekerja dan patuhi header batas laju; loop ketat sekuensial hanya akan mengantri dan habis waktu.

FAQ

Bagaimana gpt-image-2 berbeda dari gpt-image-1 di tingkat API?Endpoint yang sama, autentikasi yang sama. Parameter baru: thinking (off/low/medium/high), nilai size tambahan hingga 2000 px, dan n hingga 10 dengan gaya bersama. Integrasi SDK yang ada tetap berfungsi setelah pertukaran ID model; Anda hanya menambahkan parameter baru di mana parameter tersebut membantu. Untuk perbedaan lengkap, lihat gambaran umum ChatGPT Images 2.0.

Apa cara tercepat untuk membuat prototipe integrasi gpt-image-2?Buat permintaan di Apidog, simpan dua lingkungan (standar vs berpikir), dan ulangi prompt tanpa menyentuh kode. Ekspor permintaan akhir sebagai curl atau kode SDK ketika Anda siap untuk berkomitmen.

Apakah API mendukung pengeditan gambar atau inpainting?Endpoint edit dan variasi mengikuti pola yang sama dengan generasi sebelumnya di bawah ID model baru. Periksa referensi model gpt-image-2 untuk skema terbaru; parameter untuk mask dan gambar input didokumentasikan di sana.

Bisakah saya menggunakan gpt-image-2 untuk output komersial?Ya, di bawah kebijakan penggunaan standar OpenAI. Anda memiliki gambar yang dihasilkan; OpenAI mempertahankan hak untuk menggunakan input dan output untuk pemantauan penyalahgunaan. Karakter bermerek dagang dan tokoh publik yang disebutkan masih memicu pagar pembatas.

Bagaimana dengan biaya untuk beban kerja produksi?Dengan harga sekitar $0.21 per gambar berkualitas tinggi 1024×1024 dalam mode standar, 10.000 gambar per bulan akan menghabiskan sekitar $2.100 tanpa mode berpikir. Tambahkan 20–80% untuk mode berpikir. Bandingkan ini dengan alternatif yang di-host sendiri seperti panduan API GLM 5V Turbo dan integrasi Qwen 3.5 Omni jika anggaran lebih penting daripada kualitas puncak.

Apakah ada alternatif yang lebih murah dengan rendering teks serupa?Belum ada dengan kualitas yang sama untuk teks multibahasa. Model open-weight telah mempersempit kesenjangan dalam komposisi tetapi masih tertinggal dalam skrip CJK dan Indic.