Catatan penulis: Untuk developer yang sudah memakai image_generation dari Responses di APIYI untuk “mengobrol sambil membuat gambar”, setelah migrasi ke Images API mandiri, Anda bisa mempertahankan pengeditan gambar berkelanjutan dengan metode di artikel ini.
Kesimpulan di awal: Migrasikan hanya bagian pembuatan gambar; percakapan teks yang sudah ada tidak perlu diubah. Dulu “gambar sebelumnya” terhubung secara implisit lewat previous_response_id; sekarang aplikasi Anda sendiri yang menyimpannya, dan setiap kali melakukan pengeditan gambar, Anda memilihnya secara eksplisit lalu mengunggahnya sebagai gambar asli ke POST /v1/images/edits. Setelah itu, hasil pengeditan gambar multi-putaran tetap sama; yang berubah hanyalah siapa yang mengingat “gambar sebelumnya”.
Kesimpulan ini berlaku dengan syarat pembaruan dokumentasi yang dirilis APIYI pada 2026-11-21 22:30 (waktu Beijing). Lima model gambar resmi yang dialihkan kini direkomendasikan untuk menggunakan dua endpoint gambar independen. OpenAI tidak menghentikan Responses, dan percakapan teks di dalam platform tetap dapat digunakan seperti biasa. Semua antarmuka, field, dan ketentuan penagihan di bawah ini bersumber dari dokumentasi APIYI apiyi.com serta panduan pembuatan gambar resmi OpenAI. Kode merupakan contoh dokumentasi dan tidak mewakili hasil pengujian aktual.

Peta Pengetahuan dan Indeks Migrasi GPT Image API
Seluruh migrasi berjalan dalam empat langkah; output setiap langkah menjadi input langkah berikutnya:
Mengenali panggilan lama dan membagi rute (Bagian 1)
└─> Output: setiap permintaan harus lewat dialog, generations, atau edits
Menghasilkan dan menyimpan gambar pertama (Bagian 2.1)
└─> Output: v1.png yang sudah divalidasi + catatan aset
Menyerahkan gambar asli yang dipilih ke antarmuka edit (Bagian 2.2)
└─> Output: v2.png + relasi parent_asset_id
Verifikasi dan audit biaya (Bagian 3)
└─> Output: daftar gambar yang bisa dipakai + biaya per gambar terverifikasi

| Langkah | Bergantung pada apa | Mengapa ditempatkan di sini | Tujuan |
|---|---|---|---|
| 1 Bagi rute | Daftar panggilan di kode yang ada | Tentukan dulu bagian mana yang harus diubah, agar tidak salah mengubah dialog teks | Hanya mengalihkan permintaan pembuatan gambar ke Images API |
| 2.1 Pembuatan gambar pertama | Rute generations yang ditentukan di langkah 1 | Edit gambar selanjutnya membutuhkan gambar asli yang benar-benar tersimpan | Mendapatkan v1 yang sudah divalidasi dan menyimpannya ke database |
| 2.2 Lanjut mengedit gambar | File v1 yang disimpan di langkah 2.1 | Endpoint mandiri tidak mengenali previous_response_id, hanya mengenali gambar yang Anda unggah |
Mendapatkan v2, dan mencatat relasi induk-anak |
| 3 Verifikasi dan audit biaya | Gambar dan log konsol dari langkah 2 | Hanya gambar yang lolos verifikasi yang dihitung dalam penyebut biaya | Gambar yang bisa dikirim + tagihan yang bisa dijelaskan |
Saran urutan membaca: Bagian 1 wajib dibaca; Bagian 2 diikuti sesuai urutan kode; Bagian 3 dibaca sebelum rilis atau saat terjadi pemutusan koneksi atau pertanyaan tagihan.
To Know: Terminologi Migrasi GPT Image API
| Istilah | Penjelasan singkat |
|---|---|
| 官转 | Model jalur penerusan resmi yang disediakan APIYI, dalam artikel ini merujuk pada lima ID model gambar |
| image_generation | Alat pembuatan gambar di Responses API, jalur lama menggunakannya untuk menghasilkan gambar sambil mengobrol |
| previous_response_id | Parameter Responses untuk melanjutkan konteks putaran sebelumnya, permintaan Images mandiri tidak menerimanya |
| multipart | Format unggah formulir, /images/edits menggunakannya untuk mengirim biner gambar asli |
| b64_json | Field yang dikembalikan endpoint gambar mandiri, isinya gambar yang dikodekan base64 |
| parent_asset_id | Field relasi yang dicatat sendiri oleh aplikasi, “gambar ini diubah dari gambar mana” |
1 Pemanggilan GPT Image API mana yang perlu dimigrasikan dari Responses
1.1 Cakupan perubahan GPT Image API 11/21 dan lima model hasil konversi resmi
Pembaruan dokumentasi ini mencakup lima ID model hasil konversi resmi berikut:
gpt-image-2.6-sunburstgpt-image-2.6-flaregpt-image-2.5-sunburstgpt-image-2.5-flaregpt-image-2
Dua endpoint gambar independen yang bersesuaian adalah POST /v1/images/generations (body permintaan JSON) dan POST /v1/images/edits (formulir multipart). APIYI tidak menyarankan untuk terus memakai jalur image_generation pada Responses untuk menghasilkan gambar, karena dua alasan: pertama, pasokan tidak stabil; kedua, akan timbul biaya tool tambahan. Selain itu, Chat Completions tidak mendukung pembuatan gambar dengan kelima model gambar hasil konversi resmi ini; jika kode lama memakai cara tersebut, masukkan juga ke daftar migrasi.
Perlu dicatat, penyesuaian ini hanya memengaruhi pembuatan gambar. OpenAI tidak menghentikan Responses, dan percakapan teks di dalam situs APIYI juga tidak dihentikan. Jadi cakupan migrasi hanya terbatas pada bagian kode yang “memanggil tool gambar atau model gambar di dalam permintaan”. Cara memilih di antara kelima model adalah topik lain; silakan lihat artikel pemilihan model di pusat bantuan APIYI apiyi.com, tidak dibahas di sini.
1.2 Routing percakapan teks, pembuatan gambar pertama, dan penyuntingan gambar lanjutan pada GPT Image API
FAQ APIYI memberikan pola kombinasi: model percakapan bertugas menafsirkan maksud pengguna, lalu aplikasi memanggil Images API secara terpisah dan mengelola gambarnya sendiri. Dengan pendekatan ini, tiga hal yang sebelumnya ditangani oleh satu permintaan Responses bisa dipecah menjadi tiga rute:
| Maksud pengguna | Rute baru | Format permintaan | Sumber gambar |
|---|---|---|---|
| Obrolan teks murni, tanya jawab | Tetap memakai antarmuka percakapan teks yang sudah ada | Tidak berubah | Tidak ada |
| Pembuatan gambar pertama | POST /v1/images/generations |
JSON | Hanya prompt |
| Penyuntingan lanjutan pada gambar tertentu | POST /v1/images/edits |
multipart | Aplikasi mengunggah gambar asli yang sudah dipilih |
Pada Responses native, penyuntingan lanjutan bisa dilakukan lewat previous_response_id, atau langsung mengirim gambar. Permintaan Images yang berdiri sendiri tidak menerima previous_response_id; inilah alasan mendasar mengapa “penyuntingan gambar multi-putaran” harus diambil alih oleh aplikasi. Model tidak lagi mengingat gambar sebelumnya untuk Anda; Anda harus menyerahkan file gambar itu kepadanya.
Jika pengguna berkata “buat lebih merah sedikit”, tetapi sesi sudah memiliki beberapa versi seperti v1, v2, v3, aplikasi tidak bisa memastikan versi mana yang dimaksud. Dalam situasi ini, konfirmasikan dulu kepada pengguna, jangan menebak. Memakai versi terbaru sebagai default memang terlihat lebih praktis, tetapi jika pengguna sebenarnya ingin kembali ke v2 untuk menyunting ulang, Anda akan membuang satu kali biaya tambahan dan membuat pengguna bingung.
Parsing respons juga harus ikut berubah:

| Jalur | Lokasi gambar dalam respons | Cara melanjutkan konteks |
|---|---|---|
| Responses + image_generation | result pada item type=image_generation_call di dalam output |
previous_response_id atau mengirim gambar |
| Images API independen | data[0].b64_json |
Aplikasi mengunggah gambar asli yang sudah dipilih |
2 Cara GPT Image API Melanjutkan Edit pada Gambar Sebelumnya
Berikut contoh dua putaran untuk menjelaskan alur lengkapnya. Putaran pertama menghasilkan mug biru, putaran kedua hanya mengubah badan mug menjadi merah bata. Parameter mengikuti contoh dokumentasi APIYI: model gpt-image-2.5-sunburst, ukuran 1024x1024, quality=medium, output_format=png. Token dibaca dari variabel lingkungan APIYI_KEY dan dikirimkan dengan skema Bearer.
2.1 GPT Image API Membuat dan Memvalidasi PNG Mug Biru
Putaran pertama memanggil endpoint generations, petunjuk yang diberikan mendeskripsikan: latar belakang abu-abu muda, mug keramik biru di tengah, pegangan menghadap ke kanan, pencahayaan samping yang lembut, dan tidak ada teks di dalam gambar. Setelah mendapatkan respons, proses dengan urutan berikut:
- Panggil
raise_for_status()untuk lebih dulu menyingkirkan kegagalan di tingkat HTTP. - Lakukan decoding base64 secara ketat pada
b64_json; jika tidak bisa didekode, anggap gagal. - Buka dengan Pillow dan panggil
load()untuk memastikan file benar-benar bisa didekode menjadi gambar. - Pastikan formatnya PNG dan ukurannya 1024×1024, lalu simpan sebagai
v1.png. - Daftarkan aset ini di aplikasi; untuk pengeditan berikutnya, ambil gambar asli dari sini.
Langkah 3 tidak boleh dilewati. open() hanya membaca header file; apakah data gambar terpotong baru akan terungkap saat load().
2.2 GPT Image API mengunggah gambar asli yang dipilih, hanya mengubah badan cangkir menjadi merah bata
Putaran kedua memanggil endpoint edits. Di data kirim model, prompt, size, quality, output_format, sedangkan di files gunakan field image[] untuk mengunggah byte asli v1.png. Maksud petunjuknya: hanya ubah badan cangkir menjadi merah bata, sementara bentuk cangkir, pegangan, komposisi, pencahayaan, dan latar belakang tetap tidak berubah.
Ada beberapa titik rawan kesalahan pada langkah ini:
- Jangan kirim
response_format. - Jangan menulis
Content-Typesecara manual. requests akan otomatis membuat header multipart dengan boundary, menulis manual justru bisa membuat boundary hilang. - Jangan mengunggah string base64 sebagai file, yang diunggah harus byte asli gambar.
Setelah diubah, decode dan validasi dengan cara yang sama, lalu simpan sebagai v2.png. v1 harus tetap dipertahankan, sekaligus tulis parent_asset_id = v1 di catatan aset. Relasi induk-anak inilah yang menjadi “konteks multi-putaran” di arsitektur baru. Perlu diperhatikan juga, ini adalah pengeditan generatif, model akan berusaha semaksimal mungkin mempertahankan area lain, tetapi tidak menjamin piksel selain badan cangkir identik satu per satu.
Berikut contoh lengkap minimal (contoh dokumentasi, belum diuji langsung dalam artikel ini):
import base64
import io
import os
import uuid
import requests
from PIL import Image
BASE_URL = "https://api.apiyi.com/v1" # endpoint terpadu APIYI
API_KEY = os.environ["APIYI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
MODEL = "gpt-image-2.5-sunburst"
SIZE = "1024x1024"
# Timeout kelas menengah sebagai contoh; sesuaikan dengan jaringan dan kualitas Anda. Tanpa percobaan ulang otomatis.
TIMEOUT = (10, 360)
assets = {} # asset_id -> {"path": ..., "parent_asset_id": ...}
def decode_and_check(resp, path):
resp.raise_for_status()
item = resp.json()["data"][0]
b64 = item.get("b64_json")
if not b64:
raise ValueError("no b64_json in response, check body before any resend")
raw = base64.b64decode(b64, validate=True)
img = Image.open(io.BytesIO(raw))
img.load()
if img.format != "PNG" or img.size != (1024, 1024):
raise ValueError(f"unexpected image: {img.format} {img.size}")
with open(path, "wb") as f:
f.write(raw)
return path
def save_asset(path, parent_asset_id=None):
asset_id = str(uuid.uuid4())
assets[asset_id] = {"path": path, "parent_asset_id": parent_asset_id}
return asset_id
# Putaran 1: teks ke gambar via JSON
gen_resp = requests.post(
f"{BASE_URL}/images/generations",
headers=HEADERS,
json={
"model": MODEL,
"prompt": (
"Light gray background, a blue ceramic mug centered, "
"handle facing right, soft side lighting, no text."
),
"size": SIZE,
"quality": "medium",
"output_format": "png",
},
timeout=TIMEOUT,
)
v1_id = save_asset(decode_and_check(gen_resp, "v1.png"))
# Putaran 2: edit gambar asli yang dipilih secara eksplisit via multipart
selected_id = v1_id # jika versi target pengguna tidak jelas, tanya dulu
with open(assets[selected_id]["path"], "rb") as f:
edit_resp = requests.post(
f"{BASE_URL}/images/edits",
headers=HEADERS, # tanpa Content-Type manual; requests yang mengatur boundary
data={
"model": MODEL,
"prompt": (
"Change only the mug body to brick red. Keep the mug shape, "
"handle, composition, lighting and background unchanged."
),
"size": SIZE,
"quality": "medium",
"output_format": "png",
},
files={"image[]": ("v1.png", f, "image/png")},
timeout=TIMEOUT,
)
v2_id = save_asset(decode_and_check(edit_resp, "v2.png"), parent_asset_id=selected_id)
print(assets)
Nilai timeout=(10, 360) dalam contoh hanyalah pengaturan kelas menengah dalam dokumentasi, nilai sebenarnya perlu ditentukan berdasarkan jalur jaringan dan tingkat kualitas gambar Anda. Contoh ini juga sengaja tidak menulis percobaan ulang otomatis, alasannya lihat bagian 3.2.
🚀 Verifikasi cepat: set
APIYI_KEYke token yang Anda buat di konsol APIYI apiyi.com, skrip di atas bisa menjalankan dua putaran proses. Pengguna baru bisa memakai kuota uji gratis terlebih dahulu untuk memastikan logika routing dan parsing, lalu beralih ke trafik produksi.

3 Cara memverifikasi dan mencocokkan tagihan setelah migrasi GPT Image API
3.1 Empat pemeriksaan verifikasi gambar GPT Image API
Sebuah gambar baru bisa ditandai “layak pakai” di aplikasi hanya jika keempat pemeriksaan ini lolos semua:
- HTTP berhasil:
raise_for_status()tidak melempar exception. - Dapat didekode: decoding base64 secara ketat berhasil, dan Pillow
load()berhasil. - Spesifikasi benar: format dan ukuran sesuai permintaan; dalam contoh ini PNG, 1024×1024.
- Perubahan visual benar-benar terjadi: badan cangkir pada v2 memang berubah menjadi merah bata, sementara bentuk cangkir, gagang, komposisi, dan latar belakang pada dasarnya tetap sama.
Pemeriksaan ke-4 memerlukan pengecekan manual atau tahap audit terpisah, karena kode status HTTP tidak bisa menunjukkan apakah model sudah mengubah gambar dengan benar. Gambar yang hanya lolos tiga pemeriksaan pertama paling banter dianggap “valid secara teknis” dan belum bisa diserahkan. Jika respons tidak berisi gambar sama sekali, periksa dulu isi respons sebelum memutuskan untuk mengulang; masalah ini dibahas khusus di pusat bantuan dan tidak diulang di artikel ini.
3.2 Biaya alat lama GPT Image API dan biaya per gambar terverifikasi
Sebelum dan sesudah migrasi, dasar penghitungan tagihan berbeda:
| Item | Alur image_generation Responses lama | Images API mandiri |
|---|---|---|
| Biaya tambahan | Sekitar $0.20 biaya pemanggilan tambahan alat gambar APIYI | Tidak ada biaya alat ini |
| Arti angka tersebut | Hanya merujuk pada biaya alat tambahan ini, bukan harga total pesanan, dan juga bukan harga umum OpenAI | Penagihan berdasarkan pemakaian |
| Cara perbandingan yang cocok | Bandingkan berdasarkan “biaya per gambar terverifikasi” | Bandingkan berdasarkan “biaya per gambar terverifikasi” |
Jangan hanya membandingkan harga satuan; sebaiknya gunakan rumus berikut secara konsisten:
Biaya per gambar terverifikasi = total tagihan aktual terkait (termasuk pemanggilan teks yang diperlukan, permintaan gagal yang sudah ditagih, dan percobaan ulang) ÷ jumlah gambar yang lolos verifikasi
Semua tagihan terkait harus dimasukkan ke pembilang, termasuk pemanggilan percakapan untuk menentukan maksud, permintaan gagal yang sudah ditagih, dan percobaan ulang. Penyebut hanya menghitung gambar yang lolos keempat pemeriksaan di bagian 3.1. Jika tidak ada satu pun gambar yang lolos, jangan menghitung biaya per gambar, karena kesimpulannya seharusnya “alurnya bermasalah”, bukan “harga satuannya mahal”. Berapa banyak yang bisa dihemat dari migrasi bergantung pada tingkat percobaan ulang dan tingkat kelulusan verifikasi Anda; artikel ini tidak memberikan persentase spesifik.
Data pencocokan tagihan berasal dari log konsumsi di konsol, dengan catatan konsumsi type=2. Jika yang dibaca adalah field quota, konversikan ke nominal uang menggunakan quota ÷ 500000 sesuai dokumentasi platform.
Penanganan koneksi terputus perlu perhatian khusus. Endpoint gambar mandiri mengembalikan respons secara sinkron; jika koneksi terputus di tengah jalan, permintaan ini mungkin sudah ditagih dan gambar tidak bisa diambil kembali melalui request ID. Urutan yang benar: cek dulu log konsumsi di konsol APIYI apiyi.com untuk memastikan apakah permintaan ini sudah ditagih, baru putuskan apakah perlu mengirim ulang. Inilah alasan kode contoh tidak menyertakan percobaan ulang otomatis; percobaan ulang otomatis sangat mudah menyebabkan tagihan ganda saat koneksi terputus. Jika mengalami pembatasan laju atau perlu beralih kanal, lihat artikel pusat bantuan tentang pemilihan kanal dan degradasi 429.
Kriteria kelulusan migrasi sangat langsung: dialog teks tetap berfungsi seperti biasa; pembuatan gambar putaran pertama secara konsisten mengembalikan v1 yang lolos keempat pemeriksaan; setiap perubahan gambar dapat ditemukan dengan parent_asset_id yang jelas di catatan aset; dan setiap tagihan gambar di log konsol dapat dipetakan ke satu gambar terverifikasi, satu kegagalan yang diketahui, atau satu pengiriman ulang yang tercatat. Setelah semua ini terpenuhi, sisa lalu lintas pembuatan gambar dari Responses dapat dialihkan ke Images API. Saat membutuhkan pengujian perbandingan multi-model, APIYI apiyi.com menyediakan antarmuka kompatibel OpenAI yang terpadu; saat mengganti model, cukup ubah satu parameter MODEL.
Referensi
-
Pembaruan Dokumentasi APIYI: Model Gambar Resmi Beralih ke Images API
- Tautan:
docs.apiyi.com/live/2026-11/gpt-image-official-relay-images-api - Keterangan: Lima ID resmi, dua endpoint independen, dan alasan jalur lama tidak direkomendasikan
- Tautan:
-
APIYI FAQ: Menangani Teks dan Gambar Sekaligus dalam Satu API
- Tautan:
docs.apiyi.com/faq/text-and-image-in-one-api - Keterangan: Model percakapan menentukan niat, aplikasi memanggil Images API secara terpisah
- Tautan:
-
Panduan Pembuatan Gambar OpenAI
- Tautan:
developers.openai.com/api/docs/guides/image-generation - Keterangan: Cara pengeditan berkelanjutan di Responses dan struktur respons
- Tautan:
-
APIYI GPT Image 2 Teks ke Gambar / Pengeditan Gambar
- Tautan:
docs.apiyi.com/api-capabilities/gpt-image-2/text-to-image - Tautan:
docs.apiyi.com/api-capabilities/gpt-image-2/image-edit - Keterangan: Parameter permintaan, unggahan multipart, dan contoh validasi dekode
- Tautan:
-
APIYI Responses Image Tool / Praktik Terbaik Image API / Pencarian Log
- Tautan:
docs.apiyi.com/api-capabilities/gpt-image-2/responses-image-tool - Tautan:
docs.apiyi.com/api-capabilities/image-api-best-practices - Tautan:
docs.apiyi.com/api-capabilities/log-query - Keterangan: Perhitungan biaya tool, penanganan koneksi terputus, dan konversi log konsumsi
- Tautan:
Penulis: Tim Teknis APIYI
Diskusi Teknis: Jika Anda mengalami masalah routing atau penagihan selama migrasi, jangan ragu menghubungi kami melalui halaman utama APIYI apiyi.com. Untuk detail antarmuka lebih lanjut, silakan lihat pusat dokumentasi docs.apiyi.com
