GPT Image 2 / 2.5: generation and image editing

İsteği yazmadan önce uç noktayı seçin: metinden görüntüye için /images/generations; görüntüden görüntüye için yüklenmiş görüntü dosyalarıyla birlikte /images/edits kullanılır. Bir istemde “referans görüntü 1” ifadesini anmak bir görüntü eklemez.

Modeller ve uç noktalar

Model ID	Metinden görüntüye	Görüntüden görüntüye
gpt-image-2	/images/generations	/images/edits + görüntü dosyaları
gpt-image-2.5-sunburst	/images/generations	/images/edits + görüntü dosyaları
gpt-image-2.5-flare	/images/generations	/images/edits + görüntü dosyaları

Bunlar ayrı model ID'leridir. Model değiştirirken model değerini açıkça değiştirin; GPT Image 2.5, GPT Image 2'nin bir takma adı değildir. Güncel kullanılabilirliği ve hesap fiyatlandırmasını marketplace üzerinden kontrol edin.

İşlem	Yöntem ve uç nokta	İstek formatı
Metinden görüntüye	POST https://apimaster.ai/v1/images/generations	JSON
Görüntüden görüntüye / düzenleme	POST https://apimaster.ai/v1/images/edits	Gerçek görüntü dosyalarıyla multipart/form-data
Asenkron görüntü düzenleme	POST https://apimaster.ai/v1/images/edits/async	Düzenlemelerle aynı multipart dosyaları; bir görev ID'si döndürür
Asenkron metinden görüntüye	POST https://apimaster.ai/v1/images/generations/async	JSON; bir görev ID'si döndürür
Görev sorgulama	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Bearer kimlik doğrulaması

Görüntü düzenleme görev yanıtı için /images/edits/async kullanın. Senkron düzenlemelerdekiyle aynı dosyaları ve alanları yükleyin, ardından /tasks/{task_id} uç noktasını sorgulayın. Bir düzenleme isteğini generations/async uç noktasına taşımın. Bu görev uç noktaları mevcut asenkron sözleşmeyi yeniden kullanır: asenkron bir upstream görevini hemen döndürebilirken, senkron bir upstream ağ geçidi bir görev ID'si döndürmeden önce düzenlemeyi tamamlayabilir. Bunlar anında arka planda çalıştırma vaadi değildir. Bu modeller için Chat Completions kullanmayın.

Kimlik doğrulama ve zaman aşımları

Bir API anahtarı oluşturun ve Authorization: Bearer YOUR_API_KEY gönderin. JSON oluşturma istekleri Content-Type: application/json kullanır. Dosya yüklemelerinde multipart sınırını cURL'ün veya HTTP kütüphanenizin üretmesine izin verin; Content-Type başlığını manuel olarak ayarlamayın.

Temel istekler için en az 180 saniye, daha yüksek çözünürlük için 300 saniye, zorlayıcı düzenlemeler veya yüksek kalite için 600 saniye tanıyın. Bir istemci zaman aşımı, upstream isteğinin durduğunu kanıtlamaz. Anında yinelenen gönderimlerden kaçının.

Metinden görüntüye: JSON oluşturma

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

Sunburst veya Flare için model ID'yi gpt-image-2.5-sunburst veya gpt-image-2.5-flare ile değiştirin. Bu örneğe referans görüntü eklemeyin; aşağıdaki düzenleme örneklerini kullanın.

Görüntüden görüntüye: tek referans yükleme

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"

reference.png değerini mevcut bir yerel görüntüyle değiştirin. @, cURL'e dosya baytlarını yüklemesini söyler; image=reference.png ise yalnızca bir dosya adı dizesi gönderir. Bu uç nokta kalıbı gpt-image-2 ve gpt-image-2.5-sunburst için de geçerlidir.

Görüntüden görüntüye: birden fazla referans yükleme

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"

Her dosya için, istemde açıklanan sırayla aynı image[] alanını tekrarlayın. n, referans sayısını değil, çıktı görüntüsü sayısını belirtir. Referans sınırları seçilen modele ve mevcut rotaya bağlıdır; evrensel bir 16 görüntü sınırı varsaymayın. Tek bir referans ve n=1 ile başlayın, ardından gerektiğinde girdi ekleyin.

Python düzenleme örneği

requests paketini yükleyin. Bu örnek gerçek bir dosya yükler ve hem URL hem de base64 görüntü yanıtlarını işler.

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

Birden fazla dosya için, files çağrısına tekrarlanan ("image[]", (filename, file_object, mime_type)) girdilerinden oluşan bir liste geçirin. İstek tamamlanana kadar her dosyayı açık tutun.

Asenkron görüntü düzenleme

Uygulamanız görev ID'leri tükettiğinde bu uç noktayı GPT Image 2, Sunburst veya Flare ile kullanın. Dosya yükleme kuralları, referans sıralaması, yetenek sınırları ve kimlik doğrulama senkron düzenlemelerle aynıdır.

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"

Gönderim data[0].task_id döndürür. Aynı model ID ile sorgulayın:

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

Tamamlanmış bir izlenen görev şu şekildedir; her üretilen görüntü dahil edilir:

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

Görev, gönderimi yapan hesaba aittir. Onu o hesap için geçerli bir API anahtarıyla sorgulayın. Başarısız bir gönderim, kullanılabilir bir görev yerine bir hata döndürür; bir görev ID'si döndürüldükten sonra düzenlemeyi yeniden göndermek yerine o görevi sorgulamaya devam edin. Aşağıdaki sorgulama durum tablosuna bakın.

Mevcut URL veya base64 entegrasyonları

Girdiniz bir URL ise, görüntüyü uygulamanızda indirin ve baytlarını /images/edits uç noktasına yükleyin. Girdi bir base64 veri URI'si ise, yükü bir dosyaya veya bayt tamponuna çözün ve yükleyin. URL'yi veya base64 metnini dosya yüklemesi gibi göndermeyin.

Bazı GPT Image 2 rotaları, generations üzerinde image_urls uzantısını destekler. Bu taşınabilir bir görüntü düzenleme sözleşmesi değildir ve GPT Image 2.5 ile çalışacağı varsayılmamalıdır. Yeni entegrasyonlar yukarıdaki multipart düzenleme örneklerini kullanmalıdır. image_urls, image veya images içeren bir JSON isteği, düzenlemelere dosya yüklemeye eşdeğer değildir.

Parametreler ve yetenek sınırları

Alan	Kullanım
model	Zorunlu; yukarıdaki tablodan tam bir model ID kullanın
prompt	Zorunlu; sonucu ve referans sırasını açıklayın
image / image[]	Düzenlemeler için yüklenen gerçek dosyalar; temel örnekler için PNG veya JPEG kullanın
n	Çıktı görüntüsü sayısı; 1 ile başlayın; maksimum rotaya bağlıdır
size	İsteğe bağlı; 1024x1024 temel örnektir; diğer piksel boyutları veya en-boy oranları rotaya bağlıdır
resolution	1k, 2k, 4k gibi isteğe bağlı, rota-özel uzantı; her model/rota her katmanı desteklemez
quality	İsteğe bağlı; kabul edilen değerler ve maliyet rotaya bağlıdır
background, output_format, output_compression	İsteğe bağlı; şeffaflık ve çıktı kodlaması rota desteği gerektirir
mask	Yalnızca GPT Image 2, mevcut bir düzenlemeler rotası yüklenen maskeleri destekliyorsa; mevcut GPT Image 2.5 multipart işleyicisi tarafından desteklenmez

GPT Image 2 için maske desteği, sıradan referans düzenlemesinden ayrı olarak kontrol edilmelidir. Uyumlu bir PNG maskesi girdi boyutlarıyla eşleşmeli ve bir alfa kanalı içermelidir. Mevcut GPT Image 2.5 multipart uç noktası yüklenen maske dosyalarını reddeder; yukarıdaki Sunburst veya Flare örneklerine maske eklemeyin. Seçilen rotayı kontrol etmeden bir JSON mask_url geçici çözümünün desteklendiğini varsaymayın.

Yalnızca ihtiyacınız olan isteğe bağlı alanları gönderin. Bunlar uygun rotaları ve fiyatı değiştirebilir; bir varsayılanı açıkça ayarlamak her zaman onu atlamakla eşdeğer değildir. Üç model ID'nin tamamına eşit olarak uygulanan sabit bir piksel boyutu tablosu veya gelişmiş parametre listesi yoktur. Gerçek fiyatlandırma ve desteklenen yetenekler marketplace'i ve istek yanıtını takip eder.

Senkron yanıtlar

Başarılı bir oluşturma veya düzenleme, data içinde görüntü girdileri döndürür:

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

Rotaya ve çıktı formatına bağlı olarak, bir girdi bunun yerine b64_json içerebilir. Onu görüntü baytlarına çözün. Geçici sonuç URL'lerini hemen indirin. Bir HTTP 200 yanıtı veya tek başına görüntü sayısı, referans ayrıntılarının korunduğunu kanıtlamaz; sonucu girdiyle karşılaştırarak inceleyin.

Asenkron görevler: gönderim ve sorgulama

Metinden görüntüye için, referans görüntüler olmadan JSON'u generations/async uç noktasına gönderin. Görüntü düzenleme için, yukarıdaki multipart edits/async örneğini kullanın. Her ikisi de aynı görev sorgulama uç noktasını kullanır:

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

Gönderim zarfı normalde submitted bildirir; bir upstream zaten bir tamamlanma durumu bildiriyor olabilir. İlk sorgulama zaten tamamlanmış olabilir. Bir görev ID'si anında bir yanıt garanti etmez: seçilen upstream senkron ise, platform görevi döndürmeden önce oluşturmanın bitmesini bekler. Yeterli bir gönderim zaman aşımı tutun.

Gönderimde kullanılan aynı model ID ile sorgulayın:

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

Görev durumu	Eylem
pending, submitted, processing, in_progress	Bekleyin; 3–5 saniye sonra tekrar sorgulayın
succeeded, success, completed	data.result.images içindeki her girdiyi okuyun; izlenen görevler bir dize url kullanırken, eski upstream yanıtları bir URL dizisi kullanabilir
failed, error, cancelled	Sorgulamayı durdurun ve hatayı inceleyin

10 dakika gibi sonlu bir genel sorgulama son teslim tarihi kullanın. Süre dolarsa, otomatik olarak başka bir ücretli görev oluşturmak yerine görev ID'sini sonraki kontroller için saklayın. Görev sorgulama yanıtları ile senkron görüntü yanıtları farklı yapılara sahiptir.

Referans görüntülerinde sorun giderme

1. Gerçek istek yolunun /v1/images/edits veya /v1/images/edits/async olduğunu, generations veya generations/async olmadığını doğrulayın.
2. Multipart bölümünün, üretilmiş bir sınırla birlikte image altında veya tekrarlanan image[] alanında dosya baytları içerdiğini doğrulayın. İstem metni, dosya adları ve referans sayıları dosyaların yerini tutmaz.
3. Tam model ID'yi kontrol edin. Bir GPT Image 2 uzantısı, Sunburst veya Flare tarafından otomatik olarak desteklenmez.
4. Görev/günlük ayrıntıları önizleme göstermiyorsa, görüntü gönderilmediği sonucuna varmayın: günlükler base64 verisini ve yüklenen dosya içeriklerini atlayabilir. Tersine, günlüğe kaydedilmiş bir referans sayısı, bir upstream'in görüntüleri kullandığını kanıtlamaz.
5. Ayırt edici yazı veya şekiller içeren basit bir referansla test edin ve bu ayrıntıları açıklamadan bir arka plan değişikliği isteyin. Çıktıyı görsel olarak karşılaştırın.
6. Destek için istek ID'sini (X-Oneapi-Request-Id), varsa görev ID'sini, modeli, uç noktayı, zaman damgasını, arındırılmış istek alanlarını ve referans görüntüleri saklayın. API anahtarınızı asla paylaşmayın.

Bir 400 yanıtı için uç nokta ve parametre uyumluluğunu inceleyin; 401 kimlik doğrulama hatasını, 429 bir hız/kota sınırını gösterir. Zaman aşımları veya upstream arızaları için istek/görev ID'sini saklayın ve yeniden göndermeden önce mevcut görevi veya kullanım kaydını kontrol edin.