Cara Menggunakan API gpt-image-2.5 (Flare dan Sunburst) dengan curl, Python, dan Node

OpenAI meluncurkan ChatGPT Images 2.5 pada 8 September 2026, dengan dua model API baru: gpt-image-2.5-flare dan gpt-image-2.5-sunburst. Keduanya berada di belakang titik akhir yang sama dengan gpt-image-2, jadi jika Anda mengikuti panduan API gpt-image-2 kami, sebagian besar kode Anda tetap berfungsi dengan penggantian ID model. Yang berubah adalah tangga kualitas dan bagaimana Responses API memungkinkan Anda memilih model per panggilan alat.

Panduan ini hanya mencakup jalur pengembang: generasi, pengeditan multi-bagian dengan gambar referensi dan masker, alat Responses API, streaming, dan membaca usage untuk biaya riil. Untuk apa arti rilis ini bagi pengguna ChatGPT, baca ikhtisar ChatGPT Images 2.5 kami; pos peluncuran OpenAI memiliki kerangka produk. Setiap angka di bawah ini berasal dari dokumen, halaman harga, atau kalkulator OpenAI sebagaimana dibaca pada 9 September 2026.

Sekilas API gpt-image-2.5

Tarif per-token sesuai dengan gpt-image-2; biaya per-gambar masih bergerak karena jumlah token per tingkat kualitas berubah.

Prasyarat

• Akun pengembang OpenAI pada tingkat penggunaan berbayar. Titik akhir gambar membutuhkan Tingkat 1 atau lebih tinggi, yang berarti menambahkan metode pembayaran; langganan ChatGPT tidak dihitung. Panduan kunci API OpenAI kami mencakup kunci dengan cakupan proyek.
• SDK openai resmi untuk Python atau Node.
• Cara untuk melihat pratinjau respons gambar. curl mencetak base64, menyakitkan untuk iterasi; Apidog merender gambar yang didekodekan secara langsung, dan bagian terakhir memindahkan alur kerja ke sana.

Ekspor kuncinya sekali:

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

Buat gambar dengan curl

Gunakan Flare terlebih dahulu; halaman model OpenAI menyebutnya "pilihan default untuk sebagian besar aplikasi".

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

Respons berisi array data dengan satu b64_json per gambar, ditambah objek usage dengan input_tokens dan output_tokens. Pertahankan usage; itu adalah satu-satunya sinyal biaya akurat yang Anda dapatkan. Catatan parameter dari panduan pembuatan gambar: output_format defaultnya adalah png dan OpenAI mengatakan "Menggunakan jpeg lebih cepat daripada png"; output_compression (0-100) hanya berlaku untuk jpeg dan webp; background: "transparent" gagal pada jpeg.

Python: hasilkan, lalu edit dengan gambar referensi

Panggilan SDK mencerminkan isi curl. Dekode b64_json dan tulis bait-nya.

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

Pengeditan adalah tempat model 2.5 menunjukkan keunggulannya; pos peluncuran mengatakan bahwa mereka "lebih baik dalam mengedit hanya apa yang Anda minta, sambil menjaga detail lainnya tetap sama", dan OpenAI memposisikan Sunburst untuk "kontrol yang lebih ketat dalam pengeditan". Titik akhir pengeditan bersifat multi-bagian: gambar referensi, masker opsional, dan prompt. Di mana masker transparan, model akan melukis ulang; di tempat lain ia mempertahankan aslinya.

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

Hilangkan mask dan model akan memutuskan apa yang akan diubah hanya dari prompt. Gambar referensi dikenakan biaya sebagai token masukan gambar seharga $8 per 1 Juta; OpenAI tidak memublikasikan jumlah token masukan per gambar, jadi baca usage.input_tokens.

Node dan TypeScript: tulis b64_json ke disk

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

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

Sematkan gpt-image-2.5-flare-2026-09-08 dalam produksi untuk menjaga keluaran tetap stabil saat alias bergerak.

Responses API: pembuatan gambar sebagai alat

Di sini model utama membaca prompt Anda, merevisinya, dan memanggil alat image_generation. Anda memilih model gambar dengan mengatur model di dalam definisi alat; model tingkat atas harus menjadi model utama, dan dokumen alat OpenAI menggunakan gpt-6-astra. Panduan Responses API kami mencakup bentuk permintaan. Bidang action menerima auto (default), generate, atau edit; atur edit saat Anda meneruskan gambar referensi dan ingin itu dimodifikasi, bukan ditafsirkan ulang.

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

Tindak lanjut previous_response_id menjaga gambar pertama dalam konteks, sehingga "adegan yang sama" terselesaikan tanpa mengunggah ulang file. Token model utama ditagih di atas token gambar, dan penulisan ulang prompt berarti Anda tidak dapat mereproduksi keluaran hanya dari teks prompt.

Streaming gambar parsial

Kedua API menerima partial_images (0 hingga 3). Setiap parsial membutuhkan 100 token keluaran ekstra, jadi tiga menambahkan 300 token, atau $0,009 per gambar. Layak untuk UI yang menunjukkan kemajuan; terbuang dalam pekerjaan batch.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

String jenis event yang tepat ada di panduan pembuatan gambar; pemeriksaan sufiks menjaga loop bekerja di kedua varian API. Untuk memeriksa event yang di-stream di luar kode, lihat panduan kami untuk menguji respons SSE dari API AI.

Baca penggunaan dan ubah token menjadi dolar

Peringatan OpenAI sendiri: "Tarif token yang sama tidak berarti biaya per gambar yang sama: konsumsi token dapat berbeda menurut model dan pengaturan kualitas." Kalkulator dalam panduan pembuatan gambar memberikan estimasi ini untuk token keluaran gambar saja, dengan tarif $30 per 1 Juta pada halaman harga:

Perhatikan pelabelan ulang. high pada 2.5 menggunakan 1.756 token, anggaran medium lama pada gpt-image-2; max menggunakan 7.024 token, anggaran high lama. Pertahankan quality: "high" melalui migrasi dan setiap gambar menjadi sekitar 4x lebih murah dengan anggaran medium lama; untuk anggaran high lama, pindah ke max. Perbandingan Flare vs Sunburst vs gpt-image-2 kami menghitung total biaya bulanan.

Angka kalkulator adalah perkiraan. Biaya riil berasal dari respons:

OUTPUT_RATE = 30 / 1_000_000  # dolar per token keluaran gambar
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} token = ${usd:.4f}")

Catat per permintaan; menurut OpenAI, ukuran non-persegi yang lebih besar dapat menghasilkan lebih sedikit token daripada ukuran persegi yang lebih kecil. Satu pertanyaan terbuka: tab Batch pada halaman harga hanya mencantumkan gpt-image-2, jadi anggap dukungan Batch API untuk 2.5 belum dikonfirmasi.

Kesalahan, batasan laju, dan batas waktu

• 429 batasan laju. Mundur dengan jitter dan hormati Retry-After. Halaman model 2.5 tidak memublikasikan batasan per-tingkat. Sebagai referensi, gpt-image-2 menjalankan Tingkat 1 pada 5 gambar per menit dan 100 ribu TPM, skala hingga Tingkat 5 pada 250 IPM dan 8 Juta TPM.
• insufficient_quota. Tidak ada kredit atau masih di tingkat gratis. Tambahkan penagihan; jangan coba lagi.
• Penolakan moderasi. Prompt atau gambar referensi memicu filter. Ubah kata-kata daripada mencoba lagi; moderation: "low" melonggarkan ambang batas.
• Batas waktu. OpenAI mendokumentasikan bahwa "Prompt kompleks mungkin membutuhkan waktu hingga 2 menit untuk diproses". Tetapkan batas waktu klien di atas itu; Sunburst berjalan lebih lama daripada Flare sesuai desain.

Uji Flare dan Sunburst secara berdampingan di Apidog

Iterasi terminal pada prompt gambar lambat karena Anda tidak dapat melihat keluarannya, dan nilai quality yang salah memakan biaya riil pada setiap pengiriman. Apidog adalah klien API dan platform pengujian: ia mengirimkan panggilan dan memeriksa respons; server OpenAI melakukan rendering.

1. Simpan kunci sekali. Tambahkan OPENAI_API_KEY sebagai variabel lingkungan dan referensikan sebagai Bearer {{OPENAI_API_KEY}} di header Otorisasi; kunci tidak pernah masuk ke permintaan yang disimpan.
2. Dua lingkungan, satu permintaan. Buat lingkungan bernama flare dan sunburst, masing-masing dengan variabel MODEL, dan atur "model": "{{MODEL}}" di dalam body. Ganti, kirim ulang, dan bandingkan gambar dan usage secara berdampingan. Untuk pengeditan, gunakan body form-data dengan image dan mask sebagai bidang file.
3. Dekode b64_json dalam pasca-prosesor. Skrip singkat mengambil data[0].b64_json, mendekodenya, dan menyimpan file, sehingga setiap pengiriman menghasilkan gambar yang dapat dilihat di samping JSON mentah.
4. Asertifkan biaya, lalu jadwalkan. Asertifkan bahwa usage.output_tokens tetap di bawah anggaran, misalnya 2.000 untuk render high 1536x1024, dan jalankan permintaan sebagai uji regresi berjangka waktu. Jika seseorang menaikkan kualitas menjadi max atau snapshot mengubah jumlah token, pengujian gagal sebelum tagihan muncul.

Unduh Apidog, arahkan ke kunci OpenAI Anda, dan Anda memiliki pustaka prompt bersama dengan pengaman biaya.

FAQ

Apakah saya perlu mengubah kode gpt-image-2 saya untuk menggunakan 2.5? Tukar ID model dan periksa kembali quality. Titik akhir, otentikasi, dan bentuk respons tidak berubah, tetapi high sekarang memetakan ke anggaran token yang lebih kecil. Panduan API gpt-image-2 masih mencakup model yang lebih lama.

Flare atau Sunburst untuk API? Mulai dengan Flare. OpenAI memposisikannya sebagai default dengan "latensi 50% lebih rendah" daripada gpt-image-2 dengan harga per-token yang sama. Pindah ke Sunburst ketika presisi pengeditan lebih penting daripada kecepatan, seperti citra produk yang dibuat dari foto referensi. Keduanya berbagi jumlah token kalkulator yang sama, jadi pertukarannya adalah waktu, bukan uang.

Dapatkah saya menggunakan model-model ini di Chat Completions? Tidak. Pembuatan gambar berada di Image API dan alat image_generation Responses API. Chat Completions tidak mengeksposnya.

Apakah ada cara gratis untuk mencoba 2.5 melalui API? Tidak ada tingkat API gratis abadi, dan titik akhir gambar membutuhkan Tingkat 1. Jalur riil termurah adalah quality: "low" pada 196 token, sekitar $0,006 per gambar 1024x1024. Aplikasi konsumen adalah masalah lain; lihat cara menggunakan ChatGPT Images 2.5 secara gratis.

Ke mana selanjutnya

Mulai dengan panggilan curl, konfirmasi usage.output_tokens terhadap tabel kalkulator, lalu pindahkan permintaan ke klien tempat Anda dapat melihat gambar. Tulisan Simon Willison menunjukkan Sunburst menjaga bagan tetap utuh sambil menambahkan subjek; uji perilaku pengeditan itu pada gambar referensi Anda sendiri sebelum Anda berkomitmen.