Tobias Hoffmann

Posted on Apr 22 • Originally published at apidog.com

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.

Apidog'u hemen deneyin

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.

Bu rehberin sonunda çalışan API çağrılarına, tekrar kullanabileceğiniz bir Apidog koleksiyonuna ve her parametrenin maliyetini net şekilde görebileceğiniz bir yaklaşıma sahip olacaksınız.

Ön Koşullar

İlk isteğiniz için gerekli adımlar:

API erişimi olan bir OpenAI hesabı (Geliştirici hesapları, ChatGPT Plus'tan ayrıdır; ChatGPT aboneliğinde API kredisi yoktur.)
Ücretli bir kullanım katmanı. gpt-image-2 Katman 1 ve üzeri gerektirir. Ücretsiz katmandan ilerlemek için faturalandırma eklemelisiniz.
images:write kapsamına sahip bir API anahtarı. Üretim için kullanıcı değil, proje kapsamlı anahtarları tercih edin.
Görüntü yanıtlarını önizleyebileceğiniz bir test aracı. İlk deneme için terminalde curl yeterli; sonrasında bir API istemcisi kullanın.

API anahtarınızı ortam değişkeni olarak ayarlayın:

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

Uç Nokta ve Kimlik Doğrulama

gpt-image-2 modeli için uç nokta:

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

Kimlik doğrulama için Authorization: Bearer başlığı zorunludur. JSON gövdesine model kimliği, prompt ve diğer parametreleri ekleyin. Temel bir örnek:

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

Başarılı yanıtta data dizisi döner; hata durumunda code ve message içeren standart bir hata zarfı gelir.

İstek Parametreleri

Her parametre maliyeti ve çıktıyı değiştirir. İşte tam parametre haritası:

Parametre	Tip	Değerler	Notlar
`model`	string	`gpt-image-2`	Zorunlu.
`prompt`	string	32.000 karaktere kadar	Zorunlu. Uzun istemler fazla token harcar.
`size`	string	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	Çıktı token sayısını etkiler.
`quality`	string	`standard`, `high`	`high` kalite 2 kat pahalıdır, ince metinler için gereklidir.
`n`	integer	1–10	Toplu isteklerde ortak stil.
`thinking`	string	`off`, `low`, `medium`, `high`	Oluşturmadan önce planlama bütçesi.
`response_format`	string	`url`, `b64_json`	URL'ler 1 saat içinde sona erer.
`user`	string	Serbest biçimli	Kötüye kullanım tespiti için. Hash kullanın.
`background`	string	`auto`, `transparent`, `opaque`	Alfa kanallı PNG için `transparent`.
`seed`	integer	Herhangi bir int32	Yaklaşık tekrar edebilirlik.

Maliyet üzerinde en çok etkili üç parametre: size, quality, thinking. thinking: "high" ve büyük boyutta bir istek, temel 1024x1024 standarda göre 4–5 kat pahalıdır.

Python Örneği

Resmi OpenAI SDK'sı (openai>=1.50.0) ile örnek kullanım:

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

response.data her zaman bir listedir, n=1 olsa bile döngü kullanın.
b64_json script ile işlemek için kolaydır; CDN veya S3'e yükleyecekseniz url formatını tercih edin.

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`);

Resmi SDK, fetch'e göre hata yönetimi, yeniden deneme ve şema değişikliklerine karşı daha dayanıklıdır. Tercih edin.

Düşünme Modu: Ne Zaman Kullanılır?

thinking parametresi modelin görsel düzeni planlaması için ek hesaplama süresi tanımlar:

off: Planlama yok. Hızlı ve ucuz, serbest yaratıcı istemler için.
low: Hafif planlama. Ürün görselleri için iyi varsayılan.
medium: Yoğun planlama. Diyagramlar, infografikler ve çoklu öğeler için.
high: Maksimum planlama. Karmaşık düzenler ve teknik diyagramlar için; gecikme ve maliyet artar.

Kural: İsteminizde sayı, etiket veya pozisyon kısıtı varsa bir üst seviyeye çıkın. Sadece “sakin bir sahne” gibi ise bir seviye düşürün.

Düşünme modu ek token maliyeti yaratır. OpenAI fiyatlandırma sayfasından oranları kontrol edin; medium veya high ile temel maliyete %20-80 ekleyin.

Toplu Oluşturma

n > 1 ile, ortak kompozisyon ve stil ile birden fazla görüntü tek cevapta döner. Paralel ayrı istekler ile aynı değildir.

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",
)

n kadar görüntü için ayrı ayrı ödeme yaparsınız. Tutarlılık avantajı elde edersiniz, maliyet avantajı yoktur.

Yanıt Biçimi ve Depolama

b64_json: Görüntü yanıtın içinde base64 olarak gelir. Script ile işlemek kolaydır. Büyük boyutlu (ör. 2000 px, high quality) yanıtlar 3MB+ olabilir.
url: Görüntü OpenAI CDN'de 1 saat tutulur. Kendi depolamanıza aktarmak için idealdir.

Üretimde, URL'yi hemen indirip kendi S3, R2 veya Cloudflare Images gibi depolamanıza aktarın. OpenAI URL'lerini son kullanıcıya iletmeyin; süreleri dolacaktır.

Hata İşleme ve Oran Sınırlamaları

gpt-image-2 için tipik hata kodları ve çözümleri:

HTTP	`kod`	Neden	Çözüm
400	`invalid_request_error`	Geçersiz boyut, desteklenmeyen oran, 32k karakterden uzun prompt	Boyutları ve prompt uzunluğunu kontrol edin.
401	`invalid_api_key`	Yanlış/eksik anahtar	`OPENAI_API_KEY`'i tekrar ayarlayın.
403	`insufficient_quota`	Kredi yok, ücretsiz katman	Faturalandırma ekleyin, katmanınızı kontrol edin.
429	`rate_limit_exceeded`	Aşırı istek	Geri çekilme ile tekrar deneyin (`Retry-After` başlığı).
429	`image_generation_user_error`	İçerik politikası reddi	Prompt'u yeniden yazın.
500	`server_error`	Geçici hata	Üstel geri çekilme ile tekrar deneyin.
503	`overloaded`	Sunucu yoğunluğu	Bekleyin ve tekrar deneyin.

Oran sınırı katman tabanlıdır. Katman 1 genellikle dakika başına 50 istekle başlar; üst katmanlarla artar. Yanıtlardaki x-ratelimit-remaining-requests ve x-ratelimit-remaining-tokens başlıklarını takip edin.

Yeniden denenebilir hata yönetimi için örnek:

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, 401 veya içerik politikası 429 hatalarını tekrar denemek kredinizi boşa harcar; yalnızca geçici ve oran hatalarında retry uygulayın.

API'yi Apidog ile Test Etme

Terminalde görüntü oluşturma üzerinde yineleme yapmak verimsizdir: sonucu göremez, parametre değişikliklerini karşılaştıramaz ve iyi promptları sürümleyemezsiniz. Amaca uygun bir API istemcisi bu sorunları çözer.

Apidog, gpt-image-2 uç noktasını birinci sınıf destekler. Temel iş akışı:

OpenAI koleksiyonunda yeni bir istek oluşturun: POST metoduyla https://api.openai.com/v1/images/generations.
Authorization: Bearer {{OPENAI_API_KEY}} başlığını ekleyin; anahtarı ortam değişkenine yazın.
JSON gövdesini (prompt ve parametreler) yapıştırın; Apidog, OpenAPI şemasına göre doğrulama yapar.
Gönder'e tıklayın. Gelen görüntüler satır içi görünür; iyi olanları kaydedin, kötü olanları etiketleyin, varyant için çatallayın.
Farklı thinking seviyeleri için ortamlar kaydedin; aynı promptu çeşitli muhakeme seviyelerinde karşılaştırın.

Apidog'un istek karşılaştırma (diffing) özelliği hızlı parametre denemeleri için idealdir; bir değişiklik sonrası önceki ve yeni görüntüyü yan yana görebilir, kazananı ekip kütüphanenize ekleyebilirsiniz. Bu iş akışı terminalde mümkün değildir.

Eğer genel bir HTTP istemcisinden veya bozulmuş bir Postman alanından geliyorsanız, Apidog'u indirin ve OpenAI anahtarınızı tanımlayın; kurulum 5 dakikadan kısadır. Alternatifleri değerlendiren ekipler, Postman olmadan API testi kılavuzunu ve Apidog VS Code uzantısı genel bakışını inceleyebilirler.

Yaygın Tuzaklar

Metin ağırlıklı promptlarda quality: "standard" kullanmak: Küçük metinler bozulur. UI, etiket veya ikon metni için high kullanın.
Çok uzun promptlar: 32k karakter sınırdır, hedef değil. 500 kelimeyi aşmayın; karmaşık kısıtlamalar için thinking kullanın.
seed ile tam tekrar beklemek: Seed, varyansı azaltır ama aynı çıktıyı garanti etmez. Mutlak tekrar için çıktıyı önbelleğe alın.
OpenAI URL'lerini son kullanıcıya vermek: Süreleri bir saat içinde dolar. Yayınlamadan önce kendi depolamanıza kopyalayın.
API'yi sıkı döngüde çağırmak: Görüntü üretimi yavaştır. Paralel işleyin ve oran başlıklarına uyun.

Sıkça Sorulan Sorular

gpt-image-2 ile gpt-image-1 arasındaki API farkı nedir? Aynı uç nokta ve kimlik doğrulama. Yeni parametreler: thinking, 2000 piksele kadar yeni size seçenekleri, n ile 10'a kadar toplu çıktı. Mevcut SDK entegrasyonları model kimliği güncellenerek çalışır. Detay için ChatGPT Images 2.0 genel bakışına bakın.

En hızlı prototipleme yolu nedir? Apidog'da istek oluşturun, standart ve düşünme ortamlarını kaydedin, kod yazmadan prompt üzerinde iterasyon yapın. Son isteği curl veya SDK koduna aktarabilirsiniz.

API, görüntü düzenleme veya inpainting destekliyor mu? Düzenleme ve varyasyon uç noktaları yeni modelle aynı şemayı izler. gpt-image-2 model referansı üzerinden maskeler ve giriş görselleri ile ilgili parametreleri görebilirsiniz.

Ticari kullanım mümkün mü? Evet, OpenAI standart kullanım politikaları dahilinde. Üretilen görseller size aittir; OpenAI, kötüye kullanım tespiti için girdi/çıktıyı izleyebilir. Ticari marka ve ünlü kişi promptları ise koruyucu önlemleri tetikler.

Üretim maliyeti nedir? 1024x1024 high quality görüntü başına yaklaşık $0.21. Ayda 10.000 görsel (düşünme modu olmadan) yaklaşık $2.100. Düşünme modu için %20–80 ekleyin. Daha düşük maliyet isterseniz, GLM 5V Turbo API ve Qwen 3.5 Omni gibi alternatifleri karşılaştırın.

Daha ucuz, benzer metin işleme alternatifi var mı? Çok dilli metinler için aynı kalitede açık model yok. Açık ağırlıklı modeller kompozisyon konusunda ilerlese de CJK ve Hint dillerinde gerideler.