GPT Image 2 / 2.5: generation dan pengeditan gambar

Pilih endpoint sebelum menulis request: text-to-image menggunakan /images/generations; image-to-image menggunakan /images/edits dengan file gambar yang diunggah. Menyebut “reference image 1” dalam sebuah prompt tidak melampirkan gambar.

Model dan endpoint

ID Model	Text-to-image	Image-to-image
gpt-image-2	/images/generations	/images/edits + file gambar
gpt-image-2.5-sunburst	/images/generations	/images/edits + file gambar
gpt-image-2.5-flare	/images/generations	/images/edits + file gambar

Ini adalah ID model yang berbeda. Ubah model secara eksplisit saat berpindah model; GPT Image 2.5 bukan alias dari GPT Image 2. Periksa ketersediaan terkini dan harga akun di marketplace.

Operasi	Metode dan endpoint	Format request
Text-to-image	POST https://apimaster.ai/v1/images/generations	JSON
Image-to-image / pengeditan	POST https://apimaster.ai/v1/images/edits	multipart/form-data dengan file gambar yang sebenarnya
Pengeditan gambar asinkron	POST https://apimaster.ai/v1/images/edits/async	File multipart yang sama dengan edits; mengembalikan task ID
Text-to-image asinkron	POST https://apimaster.ai/v1/images/generations/async	JSON; mengembalikan task ID
Query sebuah task	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Autentikasi Bearer

Untuk respons task dari pengeditan gambar, gunakan /images/edits/async. Unggah file dan field yang sama seperti edits sinkron, lalu query /tasks/{task_id}. Jangan memindahkan request pengeditan ke generations/async. Endpoint task ini menggunakan ulang kontrak asinkron yang sudah ada: upstream asinkron dapat mengembalikan task-nya dengan cepat, sementara upstream sinkron dapat menyelesaikan pengeditan sebelum gateway mengembalikan task ID. Ini bukan janji eksekusi background yang seketika. Jangan menggunakan Chat Completions untuk model-model ini.

Autentikasi dan timeout

Buat API key dan kirimkan Authorization: Bearer YOUR_API_KEY. Request generation JSON menggunakan Content-Type: application/json. Untuk unggahan file, biarkan cURL atau HTTP library Anda menghasilkan multipart boundary; jangan mengatur header Content-Type secara manual.

Sediakan setidaknya 180 detik untuk request dasar, 300 detik untuk resolusi lebih tinggi, dan 600 detik untuk pengeditan yang berat atau kualitas tinggi. Timeout klien tidak membuktikan bahwa request upstream telah berhenti. Hindari pengiriman duplikat yang langsung dilakukan.

Text-to-image: generation JSON

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Untuk Sunburst atau Flare, ganti ID model dengan gpt-image-2.5-sunburst atau gpt-image-2.5-flare. Jangan menambahkan gambar referensi pada contoh ini; gunakan contoh pengeditan di bawah.

Image-to-image: unggah satu referensi

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Ganti reference.png dengan gambar lokal yang ada. @ memberi tahu cURL untuk mengunggah byte file; image=reference.png hanya mengirim string nama file. Pola endpoint ini juga berlaku untuk gpt-image-2 dan gpt-image-2.5-sunburst.

Image-to-image: unggah beberapa referensi

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Ulangi field image[] yang sama untuk setiap file, sesuai urutan yang dijelaskan dalam prompt. n adalah jumlah gambar keluaran, bukan jumlah referensi. Batas referensi bergantung pada model dan route yang dipilih; jangan berasumsi ada batas universal 16 gambar. Mulailah dengan satu referensi dan n=1, lalu tambahkan input sesuai kebutuhan.

Contoh pengeditan dengan Python

Instal requests. Contoh ini mengunggah file asli dan menangani respons gambar baik URL maupun base64.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Untuk beberapa file, berikan daftar entri ("image[]", (filename, file_object, mime_type)) yang berulang ke files. Jaga setiap file tetap terbuka hingga request selesai.

Pengeditan gambar asinkron

Gunakan endpoint ini dengan GPT Image 2, Sunburst, atau Flare ketika aplikasi Anda mengonsumsi task ID. Aturan unggahan file, urutan referensi, batas kapabilitas, dan autentikasi sama seperti edits sinkron.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Pengiriman mengembalikan data[0].task_id. Lakukan polling menggunakan ID model yang sama:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Task yang terlacak dan telah selesai memiliki bentuk seperti ini; setiap gambar yang dihasilkan disertakan:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

Task tersebut milik akun yang mengirimkannya. Query dengan API key yang valid untuk akun tersebut. Pengiriman yang gagal mengembalikan error, bukan task yang dapat digunakan; setelah sebuah task ID dikembalikan, terus lakukan polling pada task tersebut alih-alih mengirimkan pengeditan lagi. Lihat tabel status polling di bawah.

Integrasi URL atau base64 yang sudah ada

Jika input Anda berupa URL, unduh gambar tersebut di aplikasi Anda dan unggah byte-nya ke /images/edits. Jika berupa data URI base64, dekode payload menjadi file atau byte buffer dan unggah. Jangan mengirimkan URL atau teks base64 seolah-olah itu adalah unggahan file.

Beberapa route GPT Image 2 mendukung ekstensi image_urls pada generations. Itu bukan kontrak pengeditan gambar yang portabel dan tidak boleh diasumsikan berfungsi dengan GPT Image 2.5. Integrasi baru harus menggunakan contoh multipart edits di atas. Request JSON yang berisi image_urls, image, atau images tidak setara dengan mengunggah file ke edits.

Parameter dan batas kapabilitas

Field	Penggunaan
model	Wajib; gunakan satu ID model yang persis dari tabel di atas
prompt	Wajib; jelaskan hasil dan urutan referensi
image / image[]	File yang benar-benar diunggah untuk edits; gunakan PNG atau JPEG untuk contoh dasar
n	Jumlah gambar keluaran; mulai dengan 1; maksimum bergantung pada route
size	Opsional; 1024x1024 adalah contoh dasar; dimensi piksel lain atau rasio aspek bergantung pada route
resolution	Ekstensi opsional yang spesifik route seperti 1k, 2k, 4k; tidak setiap model/route mendukung setiap tier
quality	Opsional; nilai yang diterima dan biaya bergantung pada route
background, output_format, output_compression	Opsional; transparansi dan encoding keluaran memerlukan dukungan route
mask	Hanya GPT Image 2, ketika route edits yang tersedia mendukung mask yang diunggah; tidak didukung oleh handler multipart GPT Image 2.5 saat ini

Untuk GPT Image 2, dukungan mask harus diperiksa secara terpisah dari pengeditan referensi biasa. Mask PNG yang kompatibel harus sesuai dengan dimensi input dan menyertakan alpha channel. Endpoint multipart GPT Image 2.5 saat ini menolak file mask yang diunggah; jangan menambahkan mask ke contoh Sunburst atau Flare di atas. Jangan berasumsi solusi JSON mask_url didukung tanpa memeriksa route yang dipilih.

Hanya kirim field opsional yang Anda butuhkan. Field tersebut dapat mengubah route yang memenuhi syarat dan harga; mengatur nilai default secara eksplisit tidak selalu setara dengan menghilangkannya. Tidak ada tabel ukuran piksel tetap atau daftar parameter lanjutan yang berlaku seragam untuk ketiga ID model. Harga aktual dan kapabilitas yang didukung mengikuti marketplace dan respons request.

Respons sinkron

Generation atau pengeditan yang berhasil mengembalikan entri gambar di data:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

Tergantung pada route dan format keluaran, sebuah entri mungkin justru berisi b64_json. Dekode menjadi byte gambar. Unduh URL hasil sementara segera. Respons HTTP 200 atau jumlah gambar saja tidak membuktikan bahwa detail referensi telah dipertahankan; periksa hasilnya terhadap input.

Task asinkron: pengiriman dan polling

Untuk text-to-image, kirimkan JSON tanpa gambar referensi ke generations/async. Untuk pengeditan gambar, gunakan contoh multipart edits/async di atas. Keduanya menggunakan endpoint query task yang sama:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

Envelope pengiriman biasanya melaporkan submitted; sebuah upstream mungkin sudah melaporkan status selesai. Polling pertama bisa saja sudah selesai. Task ID tidak menjamin respons yang seketika: jika upstream yang dipilih bersifat sinkron, platform menunggu generation selesai sebelum mengembalikan task. Pertahankan timeout pengiriman yang memadai.

Lakukan polling dengan ID model yang sama yang digunakan saat pengiriman:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Status task	Tindakan
pending, submitted, processing, in_progress	Tunggu; query lagi setelah 3–5 detik
succeeded, success, completed	Baca setiap entri di data.result.images; task terlacak menggunakan url berupa string, sedangkan respons upstream warisan mungkin menggunakan array URL
failed, error, cancelled	Hentikan polling dan periksa errornya

Gunakan batas waktu polling keseluruhan yang terbatas, misalnya 10 menit. Jika habis, simpan task ID untuk pemeriksaan berikutnya alih-alih otomatis membuat task berbayar lainnya. Respons query task dan respons gambar sinkron memiliki struktur yang berbeda.

Pemecahan masalah gambar referensi

1. Verifikasi bahwa path request yang sebenarnya adalah /v1/images/edits atau /v1/images/edits/async, bukan generations atau generations/async.
2. Verifikasi bahwa multipart berisi byte file di bawah image atau image[] yang berulang, dengan boundary yang dihasilkan. Teks prompt, nama file, dan jumlah referensi tidak menggantikan file.
3. Periksa ID model yang tepat. Ekstensi GPT Image 2 tidak otomatis didukung oleh Sunburst atau Flare.
4. Jika detail task/log tidak menunjukkan pratinjau, jangan menyimpulkan bahwa tidak ada gambar yang dikirim: log dapat menghilangkan data base64 dan isi file yang diunggah. Sebaliknya, jumlah referensi yang tercatat dalam log tidak membuktikan bahwa upstream menggunakan gambar-gambar tersebut.
5. Uji dengan referensi sederhana yang berisi tulisan atau bentuk yang khas, dan minta perubahan latar belakang tanpa mendeskripsikan detail tersebut. Bandingkan hasilnya secara visual.
6. Untuk dukungan, simpan request ID (X-Oneapi-Request-Id), task ID jika ada, model, endpoint, timestamp, field request yang telah dibersihkan, dan gambar referensi. Jangan pernah membagikan API key Anda.

Untuk respons 400, periksa kompatibilitas endpoint dan parameter; 401 menunjukkan kegagalan autentikasi; 429 menunjukkan batas rate/kuota. Untuk timeout atau kegagalan upstream, simpan request/task ID dan periksa task atau catatan penggunaan yang ada sebelum mengirim ulang.