gpt-image-2 API Nasıl Kullanılır?

gpt-image-2 API, OpenAI'ın 21 Nisan 2026'da ChatGPT Images 2.0 ile birlikte piyasaya sürülen yeni görüntü oluşturma uç noktasıdır. OpenAI sohbet veya gömme API'lerini zaten kullanıyorsanız, görüntü oluşturmayı eklemek tek bir yeni istek şekli, doğru kapsama sahip bir API anahtarı ve yaklaşık on dakika sürer.

Bu kılavuz tamamen API hakkındadır: kimlik doğrulama, istek parametreleri, üç dilde kod örnekleri, düşünme modu, toplu oluşturma, yanıt işleme, hata kodları, oran sınırlamaları ve bozuk istemlerde kredilerinizi yakmanızı engelleyen test iş akışı. ChatGPT Images 2.0'daki yeniliklerin ürün düzeyindeki genel bakışı için ChatGPT Images 2.0 detaylı incelememize bakın.

Sonunda çalışan çağrılara, yineleme için yeniden kullanılabilir bir Apidog koleksiyonuna ve her parametrenin ne kadara mal olduğuna dair net bir resme sahip olacaksınız.

Ön Koşullar

İlk isteğinizden önce dört şeye ihtiyacınız var:

• API erişimine sahip bir OpenAI hesabı. Geliştirici hesapları ChatGPT Plus'tan ayrıdır; bir ChatGPT aboneliği API kredilerini içermez.
• Ücretlendirilebilir bir kullanım katmanı. gpt-image-2 Katman 1 ve üzerinde mevcuttur. Yeni hesaplar Ücretsiz katmandan başlar ve görüntü uç noktalarının kilidini açmadan önce ödeme eklemelidir.
• images:write kapsamına sahip bir API anahtarı. Üretim için kullanıcı kapsamlı anahtarlar yerine proje kapsamlı anahtarlar önerilir.
• Görüntü yanıtlarını önizleyen bir test aracı. Terminal curl ilk istek için çalışır; bundan sonra gerçek bir API istemcisi kullanın. Daha fazlası aşağıda.

Anahtarı kabuğunuzda bir kez ayarlayın, böylece bu kılavuzdaki her örnek düzenleme yapmadan çalışır:

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

Uç nokta ve kimlik doğrulama

gpt-image-2 önceki modelle aynı görüntü oluşturma uç noktasını kullanır:

POST https://api.openai.com/v1/images/generations

Kimlik doğrulama, Authorization başlığında bir taşıyıcı (bearer) tokendir. Her istek ayrıca model kimliği, istem ve çıktı parametrelerini içeren bir JSON gövdesi taşır.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A sharp product hero image for an API testing platform, dark background",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

Çağrı başarılı olursa, `data` dizisi görüntüler içeren bir JSON nesnesi alırsınız. Başarısızlıklar, `code` ve insan tarafından okunabilir bir `message` içeren standart bir OpenAI hata zarfı döndürür; bu kılavuzdaki hata tablosu yaygın olanları kapsar.

İstek parametreleri

İstek gövdesindeki her alan ne ödediğinizi ve ne aldığınızı değiştirir. İşte gpt-image-2 için eksiksiz parametre haritası.

Maliyeti en çok değiştiren üç parametre size, quality ve thinking'dir. thinking: "high" ile 2000 piksel genişliğinde high kaliteli bir görüntü, temel 1024x1024 standard bir render'ın 4–5 katına mal olabilir.

Python örneği

Resmi SDK (openai>=1.50.0), gpt-image-2 için yerel destek ekler:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt=(
        "A minimalist diagram of an OAuth 2.1 authorization code flow with PKCE. "
        "Five boxes labeled in English: User, Client, Auth Server, Resource Server, Token. "
        "Sharp sans-serif text, off-white background, teal accent arrows."
    ),
    size="1536x1024",
    quality="high",
    n=2,
    thinking="medium",
    response_format="b64_json",
)

out_dir = Path("out")
out_dir.mkdir(exist_ok=True)

for i, image in enumerate(response.data):
    png_bytes = base64.b64decode(image.b64_json)
    (out_dir / f"oauth_{i}.png").write_bytes(png_bytes)

print(f"Generated {len(response.data)} images into {out_dir.resolve()}")

Vurgulanması gereken iki nokta:

• response.data, n=1 olsa bile bir listedir. Her zaman yineleyin.
• b64_json yerel betikler için daha kolaydır; url, görüntüyü bir CDN'e veya S3 yüklemesine ilettiğinizde daha iyidir, çünkü kod çözme-yeniden kodlama döngüsünü atlamış olursunuz.

Node.js / TypeScript örneği

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

const client = new OpenAI();

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt:
    "Dashboard UI mockup for a REST client, sentence-case labels, latency sparkline in the top-right, cool grey palette.",
  size: "1536x1024",
  quality: "high",
  n: 4,
  thinking: "medium",
  response_format: "b64_json",
});

await Promise.all(
  response.data.map(async (image, i) => {
    if (!image.b64_json) return;
    await fs.writeFile(`dash_${i}.png`, Buffer.from(image.b64_json, "base64"));
  }),
);

console.log(`Saved ${response.data.length} images`);

Aksi için bir nedeniniz yoksa, ham fetch yerine resmi SDK'yı kullanın. SDK, yeniden denemeyi, idempotentlik başlıklarını ve akışı işler ve model revizyonları arasındaki bozan şema değişikliklerini takip eder.

Düşünme modu: ne zaman kullanılır

thinking, modelin render etmeden önce düzeni planlamak için ne kadar hesaplama harcadığını kontrol eder. Yaklaşık olarak dört değeri vardır:

• off: muhakeme yok. En hızlı, en ucuz, kompozisyonun tam olması gerekmeyen serbest yaratıcı istemler için en iyisi.
• low: hafif planlama. Ürün çekimleri ve hero görselleri için iyi bir varsayılan.
• medium: daha yoğun planlama. Diyagramlar, infografikler, slaytlar ve sayılan öğeler içeren her şey için doğru seçimdir (“dört panel”, “üç ok”).
• high: maksimum muhakeme. Yalnızca karmaşık çok dilli düzenlerde veya katı teknik diyagramlarda işe yarar; belirgin şekilde daha yüksek gecikme ve maliyet bekleyin.

Pratik bir kural: İstem bir sayı, bir etiket veya konumsal bir kısıtlama içeriyorsa, bir katman yukarı çıkın. Sadece “rahat bir sahne” diyorsa, bir katman aşağı inin.

Düşünme modu, görüntü çıktı tokenlarına ek olarak faturaya muhakeme tokenları ekler. OpenAI fiyatlandırma sayfası mevcut token başına oranları listeler; `medium` veya `high` açıkken temel görüntü maliyetinizin 1.2–2 katını bütçenize dahil edin.

Toplu oluşturma

n > 1 olarak ayarlamak, kompozisyon ve stili paylaşan tek bir yanıtta birden fazla görüntü döndürür. Bu, uç noktayı `n` kez paralel olarak çağırmakla aynı değildir; bu size birbiriyle ilgisiz dört görüntü verir. Toplu çıktı tutarlıdır ve bir tasarım ekibinin nasıl yinelediğiyle eşleşir.

response = client.images.generate(
    model="gpt-image-2",
    prompt="Four different hero illustrations for an API documentation landing page, shared color palette, shared line weight.",
    size="1536x1024",
    quality="high",
    n=4,
    thinking="low",
)

Görüntü başına ödeme yaparsınız, bu nedenle `n=4` kabaca `n=1`'in 4 katına mal olur. Kazanım tutarlılıktır, verimlilik değil.

Yanıt biçimi ve depolama

İki format, iki kullanım durumu:

• b64_json: görüntü yanıtta satır içi olarak bulunur. Betikler için kolaydır. Yanıt yükleri hızla büyür; 2000 piksel genişliğinde yüksek kaliteli bir PNG, yanıt boyutunu 3 MB'ın üzerine çıkarabilir.
• url: görüntü OpenAI'ın CDN'inde bir saat kalır ve siz onu kendiniz indirirsiniz. Yanıt boyutu sınırlamaları olan sunucusuz fonksiyonlar ve görüntüyü kendi depolamanıza ileten boru hatları için daha iyidir.

Üretim için, URL'yi indirin ve hemen kendi S3, R2 veya Cloudflare Images deponuza aktarın. OpenAI URL'lerini son kullanıcılara göndermeyin; süreleri dolar.

Hata işleme ve oran sınırlamaları

gpt-image-2 standart OpenAI hata şekillerini döndürür. Karşılaşacağınız hatalar şunlardır:

gpt-image-2 üzerindeki oran sınırlamaları katman tabanlıdır. Katman 1'de dakika başına yaklaşık 50 istek ile başlarsınız; daha yüksek katmanlar artar. Her yanıtta x-ratelimit-remaining-requests ve x-ratelimit-remaining-tokens başlıklarını her zaman okuyun ve duvara çarpmadan önce kısıtlayın.

Üretimde yeniden denenebilir hatalar:

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def generate_with_retry(prompt: str, tries: int = 3):
    delay = 1.0
    for attempt in range(tries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
            )
        except RateLimitError:
            time.sleep(delay)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < tries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("gpt-image-2 retries exhausted")

400'leri, 401'leri veya içerik politikası 429'larını tekrar denemeyin; bunlar bir nedenden dolayı başarısız olur ve tekrar denemek kredileri boşa harcar.

API'yi Apidog ile test etme

Bir terminalden görüntü oluşturma istemleri üzerinde yineleme yapmak yavaştır: sonucu göremezsiniz, parametre değişikliklerini karşılaştıramaz ve iyi istemleri sürümleyemezsiniz. Amaca yönelik bir API istemcisi bu üç sorunu da çözer.

Apidog, gpt-image-2 uç noktasını birinci sınıf bir istek olarak ele alır. Tipik iş akışı:

1. OpenAI koleksiyonunuzda yeni bir istek oluşturun, metod POST, URL https://api.openai.com/v1/images/generations.
2. Başlık olarak Authorization: Bearer {{OPENAI_API_KEY}} ekleyin; OPENAI_API_KEY'i bir ortam değişkeninde ayarlayın, böylece kaynak kodda asla bulunmaz.
3. İsteminizi içeren JSON gövdesini yapıştırın; Apidog, OpenAPI spesifikasyonuna göre doğrular ve göndermeden önce tür uyumsuzluklarını ortaya çıkarır.
4. Gönder'e tıklayın. Görüntü yanıtları satır içi olarak oluşturulur; iyi olanları kaydedin, kötü olanları etiketleyin, varyantlar için isteği çatallayın (fork).
5. thinking: off, thinking: medium ve thinking: high için ortamları kaydederek aynı istemi muhakeme seviyeleri arasında karşılaştırın.

Apidog'un istek karşılaştırma (diffing) özelliği burada en önemli kısımdır. Bir parametreyi ayarlarsınız; önceki ve sonraki görüntüyü yan yana görürsünüz; kazananı tüm ekibinizin paylaştığı bir istem kütüphanesine kaydedersiniz. Bu, terminalin size sunamayacağı bir iş akışıdır.

Genel bir HTTP istemcisinden veya çökmüş bir Postman çalışma alanından geliyorsanız, Apidog'u indirin ve OpenAI anahtarınıza yönlendirin; kurulum beş dakikadan az sürer. Alternatifleri değerlendiren ekipler, Postman olmadan API testi kılavuzumuzu ve Apidog VS Code uzantısı genel bakışını da okuyabilirler.

Yaygın tuzaklar

gpt-image-2 ile ilk haftada yapılan birkaç hata, kredileri ve zamanı boşa harcar.

• Metin ağırlıklı istemler için `quality: "standard"` kullanmak. Standart kalite küçük metinleri bozar. Etiketler, simgeler veya UI metinleri önemli olduğunda `high` kalitesine geçin.
• Aşırı istemleme. 32k karakter tavan sınırdır, hedef değil. Birkaç yüz tokendan sonra model, önceki talimatları göz ardı etmeye başlar. İstemleri 500 kelimenin altında tutun ve karmaşık kısıtlamaları uygulamak için `thinking` kullanın.
• `seed`'den tekrarlanabilirlik beklemek. Seed, varyansı azaltır ancak çıktıyı sabitlemez. Tam olarak aynı görüntüye ihtiyacınız varsa, baytları önbelleğe alın; yeniden oluşturmayın.
• OpenAI URL'lerini dağıtmak. Bir saat içinde süreleri dolar. Alt kullanıcılara sunmadan önce her zaman kendi depolamanıza kopyalayın.
• Uç noktayı sıkı bir döngüde çağırmak. Görüntü oluşturma yavaştır. Çalışanlar arasında paralelleştirin ve oran sınırlama başlıklarına uyun; sıralı sıkı döngüler sadece kuyruğa girer ve zaman aşımına uğrar.

Sıkça Sorulan Sorular

API düzeyinde `gpt-image-2` ile `gpt-image-1` arasındaki fark nedir?Aynı uç nokta, aynı kimlik doğrulama. Yeni parametreler: `thinking` (`off`/`low`/`medium`/`high`), 2000 piksele kadar ek `size` değerleri ve paylaşılan stille `n` değeri 10'a kadar. Mevcut SDK entegrasyonları, model kimliği değiştirildikten sonra çalışmaya devam eder; yeni parametreleri yalnızca yardımcı oldukları yerlere eklersiniz. Tam fark için ChatGPT Images 2.0 genel bakışına bakın.

gpt-image-2 entegrasyonunu prototiplemenin en hızlı yolu nedir?Apidog'da bir istek oluşturun, iki ortam (standart ve düşünme) kaydedin ve koda dokunmadan istemler üzerinde yineleyin. Taahhüt etmeye hazır olduğunuzda son isteği curl veya SDK kodu olarak dışa aktarın.

API, görüntü düzenlemeyi veya inpainting'i destekliyor mu?Düzenleme ve varyasyon uç noktaları, yeni model kimliği altında önceki nesille aynı deseni takip eder. En son şema için gpt-image-2 model referansına bakın; maskeler ve giriş görüntüleri için parametreler orada belgelenmiştir.

gpt-image-2'yi ticari çıktı için kullanabilir miyim?Evet, OpenAI'ın standart kullanım politikaları altında. Oluşturulan görüntülerin sahibi sizsiniz; OpenAI, kötüye kullanım izleme için girdi ve çıktıları kullanma haklarını saklı tutar. Ticari marka korumalı karakterler ve adı geçen kamu figürleri yine de koruyucu önlemleri tetikler.

Üretim iş yükü için maliyet ne durumda?Standart modda 1024×1024 yüksek kaliteli görüntü başına yaklaşık 0,21 dolar ile ayda 10.000 görüntü, düşünme modu olmadan yaklaşık 2.100 dolara mal olur. Düşünme modu için %20–80 ekleyin. Bütçe en yüksek kaliteden daha önemliyse, bunu GLM 5V Turbo API kılavuzumuz ve Qwen 3.5 Omni entegrasyonu gibi kendi kendine barındırılan alternatiflerle karşılaştırın.

Benzer metin işleme özelliğine sahip daha ucuz bir alternatif var mı?Çok dilli metinler için aynı kalitede henüz yok. Açık ağırlıklı modeller kompozisyon konusunda farkı kapatmış olsa da CJK ve Hint dillerinde hala gerideler.