GPT Image 2.5 API: membuat dan mengedit gambar dengan Python

Kirim satu POST ke https://api.omniakey.com/v1/media/tasks dengan model gpt-image-2.5-flare, pantau id tugas yang dikembalikan, lalu unduh assets[0].url saat statusnya succeeded. Pada 29 Oktober 2026 kami membuat gambar 1K, 2K, dan 1536x1024 serta mengedit satu foto kafe, lalu membuka setiap file dan membaca ukuran piksel sebenarnya: 1024×1024, 2048×2048, 1536×1024, dan 1024×682. Pembuatan 1K memakan 29,5 dtk dan 2K 45,2 dtk.

Id model 2.5 mana yang dipakai

Gunakan gpt-image-2.5-flare. Itulah id yang kami panggil di setiap proses di bawah. Halaman model GPT-Image 2.5 Flare (diperiksa 29 Oktober 2026) mencantumkan OpenAI sebagai penyedia, mendaftar teks ke gambar dan edit gambar, serta memuat catatan "Guide updated 2026-10-27". Halaman yang sama mencantumkan id 2.5 kedua, gpt-image-2.5-sunburst.

Flare menangani kedua pekerjaan. Pembuatan mengirim prompt; edit mengirim prompt plus satu gambar sumber. Kualitas menerima low, medium, atau high, dan halaman yang sama menyebut tingkat itu tidak mengubah harga. Semua proses di sini memakai medium. Kami tidak menjalankan sunburst, kualitas low atau high, 4K atau 3840x2160, masker, atau beberapa gambar referensi, jadi rencanakan dengan Flare pada medium dan satu gambar sumber sampai Anda menguji sisanya sendiri.

Kode permintaan

Skrip di bawah adalah yang kami jalankan, tanpa perubahan: dua fungsi pembantu, lalu satu panggilan pembuatan dan satu panggilan edit. Skrip ini hanya memakai pustaka standar Python, membaca kunci Anda dari OMNIAKEY_API_KEY, dan menulis setiap PNG ke folder tempat Anda menjalankannya.

import base64
import json
import os
import time
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]
MODEL = "gpt-image-2.5-flare"

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def run_task(body, out_path):
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    for _ in range(150):
        time.sleep(4)
        state = request("GET", f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # signed link: valid for about an hour, so download now
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=120) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

def generate_image(prompt, out_path, size="1K", quality="medium"):
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "generate",
        "input": {"prompt": prompt},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

def edit_image(source_path, prompt, out_path, size="1K", quality="medium"):
    with open(source_path, "rb") as f:
        image = base64.b64encode(f.read()).decode()
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "edit",
        "input": {"prompt": prompt, "image": {"data": image, "mime_type": "image/jpeg"}},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

if __name__ == "__main__":
    task = generate_image(
        "A small glass greenhouse on a hillside at sunrise, morning fog in the valley, "
        "soft watercolor style, a wooden bench outside the door, no people, no text.",
        "greenhouse.png",
    )
    print("generate task", task)
    task = edit_image(
        "cafe-base.jpg",
        "Change the red bicycle to matte black. Keep everything else exactly the same: "
        "the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos.",
        "cafe-edited.png",
    )
    print("edit task", task)

Authorization: Bearer <key> dikirim di setiap panggilan, dan panggilan pembuatan juga memerlukan Idempotency-Key, yang diisi skrip dengan UUID baru. Body menetapkan type ke "image", operation ke "generate" atau "edit", kata-kata di input.prompt, serta ukuran dan kualitas di parameters. API juga menerima n, dan hanya 1 yang valid, jadi skrip tidak mengirimnya. Pembuatan mengembalikan HTTP 202 dengan id tugas, status dimulai dari queued, dan loop menunggu 4 dtk di antara pemeriksaan sampai status keluar dari dua keadaan kerja.

Edit menambahkan JPEG di input.image sebagai objek Base64 inline beserta tipe mimenya. Body permintaan, termasuk Base64, dibatasi 1 MiB, jadi skrip mengirim JPEG 1024 piksel berukuran sekitar 230 KB.

Ukuran yang kami jalankan dan hasilnya

Empat proses, semuanya pada kualitas medium, pada 29 Oktober 2026. Tiga kembali sesuai ukuran yang kami minta. Edit 1K tidak, pada salah satu dari dua prosesnya.

• 1K, pembuatan — Ukuran piksel yang kami baca dari file: 1024×1024; Tanggal: 29 Oktober 2026
• 2K, pembuatan — Ukuran piksel yang kami baca dari file: 2048×2048; Tanggal: 29 Oktober 2026
• 1536x1024, pembuatan — Ukuran piksel yang kami baca dari file: 1536×1024; Tanggal: 29 Oktober 2026
• 1K, edit — Ukuran piksel yang kami baca dari file: 1024×682; Tanggal: 29 Oktober 2026

Rumah kaca di bawah adalah hasil pembuatan 1K dengan body permintaan yang sama seperti kode di atas.

Dua hal bisa diambil dari daftar. Pertama, baca ukuran dari file yang Anda unduh. Edit 1K meminta persegi tetapi kembali 1024×682, bentuk JPEG 1024×683 yang kami kirim, dan proses lain dari edit yang sama pada 1K kembali 1024×1024. Kedua, daftar ukuran di dokumentasi API gambar (diperiksa 29 Oktober 2026) menawarkan auto, 1K, 2K, 4K, dan 3840x2160 untuk model ini, dan menyebut ukuran di luar daftar ditolak sebelum ada biaya; panggilan 1536x1024 kami pada 29 Oktober 2026 tidak ditolak dan mengembalikan 1536×1024. Periksa file sebenarnya sebelum menyusun tata letak berdasarkan satu ukuran. Catat juga ukuran yang diminta bersama hasilnya, supaya perbedaan seperti ini terlihat saat Anda membandingkan beberapa proses.

Edit mempertahankan adegan dan mengubah satu hal

Edit menjawab dua pertanyaan: apa yang berubah dan apa yang tetap. Kami meminta satu perubahan dan menyebut hal-hal yang harus bertahan.

Prompt: "Change the red bicycle to matte black. Keep everything else exactly the same: the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos."

Sepeda kembali gelap, dan meja, cangkir, tanaman, serta kusen jendela masih ada di bingkai. Sumbernya JPEG 1024×683, hasilnya terukur 1024×682, dan prosesnya memakan 38,0 dtk. Tulis daftar yang harus tetap setiap kali: untuk struktur prompt secara umum, lihat panduan prompt GPT Image 2 kami.

Kesalahan dan batasan

Dua header bekerja sebelum ada piksel: token bearer dan Idempotency-Key yang unik. Jika keduanya benar, sisa panggilan mudah diulang.

Kunci bisa sampai 255 karakter, menurut dokumentasi yang diperiksa 29 Oktober 2026. Mengulang dengan body yang sama adalah percobaan ulang yang aman: Anda mendapat tugas yang sudah ada dan tidak ada biaya baru. Jaga body tetap di bawah 1 MiB termasuk Base64, jadi ubah ukuran atau kompres sumber sebelum mengirim. Simpan nilai kunci selama percobaan ulang berlangsung, agar body yang sama benar-benar memakai kunci yang sama.

Saat tugas berhasil, assets[0].url adalah tautan bertanda tangan yang berlaku sekitar satu jam, menurut dokumentasi, jadi unduh segera atau pantau tugas yang sama lagi untuk tautan baru. Catatan tugas disimpan 24 jam.

Satu header mengejutkan kami pada 29 Oktober 2026: POST yang dikirim dengan User-Agent bawaan urllib Python mengembalikan HTTP 403 dengan body "error code: 1010" dari Cloudflare. POST yang sama dengan header User-Agent: omniakey-example/1 milik kami mencapai API, yang menjawab 400 invalid_request untuk body kosong yang kami kirim, dan tidak ada biaya. Dokumentasi hanya menyebut Authorization dan Idempotency-Key, jadi tetapkan User-Agent di klien Anda.

GPT Image 2.5 atau GPT Image 2 untuk pekerjaan API?

Flare adalah id 2.5 yang kami uji. GPT Image 2, di halaman model GPT Image 2, memakai id gpt-image-2. Jika skrip sudah menghasilkan yang Anda butuhkan pada id itu, tidak ada alasan untuk menggantinya.

Untuk foto yang harus mempertahankan adegan saat satu objek berubah, Flare pada medium adalah yang dicakup proses kami pada 29 Oktober 2026: tiga ukuran yang dibuat dan edit 1024×682. Perbandingan GPT Image 2.5 vs GPT Image 2 memuat ukuran dan hasil prompt yang sama untuk kedua model, jadi Anda bisa memilih dengan angka di depan mata. Tarif terkini ada di halaman harga.

Pertanyaan umum

Id model mana yang harus saya pakai, gpt-image-2.5-flare atau gpt-image-2.5-sunburst?

Kami menjalankan Flare di semua proses di atas, dan editnya mempertahankan adegan yang kami minta dipertahankan. Halaman model mencantumkan Sunburst sebagai id 2.5 kedua: mulai dengan Flare, dan uji Sunburst pada edit tersulit Anda sebelum beralih.

Bisakah saya meminta ukuran lanskap seperti 1536x1024?

Pada 29 Oktober 2026 pembuatan 1536x1024 kembali 1536×1024. Daftar ukuran di dokumentasi API gambar tidak memuat nilai itu untuk model ini, jadi baca file dan periksa dokumentasi sebelum mengandalkannya di produksi.

Mengapa hasil edit saya berbeda ukuran dari yang saya minta?

Edit 1K yang sama kembali 1024×682 pada satu proses dan 1024×1024 pada proses lain, jadi perlakukan ukuran yang diminta sebagai permintaan, bukan janji. Buka PNG dan baca lebar serta tingginya sebelum menempatkannya.

Apakah saya perlu header User-Agent?

Pada 29 Oktober 2026 permintaan dengan User-Agent bawaan Python mendapat HTTP 403 dengan error 1010 dari Cloudflare. Permintaan yang sama dengan header User-Agent milik kami mencapai API, jadi kirimkan satu.

Berapa lama tautan gambar berlaku?

Dokumentasi menyebut tautan bertanda tangan berlaku sekitar satu jam. Pantau tugas lagi untuk tautan baru, dan unduh file segera setelah tugas berhasil.