curl, Python ve Node ile gpt-image-2.5 API (Flare ve Sunburst) nasıl kullanılır

OpenAI, 8 Eylül 2026 tarihinde, iki yeni API modeli olan gpt-image-2.5-flare ve gpt-image-2.5-sunburst ile ChatGPT Images 2.5'i piyasaya sürdü. Her ikisi de gpt-image-2 ile aynı uç noktaların arkasında yer alıyor, bu nedenle gpt-image-2 API kılavuzumuzu takip ettiyseniz, kodunuzun çoğu model kimliği değişikliğinden etkilenmeden çalışacaktır. Değişen şey kalite seviyesi ve Responses API'nin her araç çağrısı için bir model seçmenize nasıl olanak tanıdığıdır.

Bu kılavuz yalnızca geliştirici yolunu kapsar: üretimler, referans görsel ve maske ile çok parçalı düzenlemeler, Responses API aracı, akış ve gerçek maliyet için usage okuma. Sürümün ChatGPT kullanıcıları için ne anlama geldiğini öğrenmek için ChatGPT Images 2.5 genel bakış yazımızı okuyun; OpenAI lansman gönderisinde ürünün çerçevesi yer almaktadır. Aşağıdaki her sayı, 9 Eylül 2026 tarihinde okunduğu haliyle OpenAI'nin belgelerinden, fiyatlandırma sayfasından veya hesaplayıcısından alınmıştır.

gpt-image-2.5 API'ye Hızlı Bakış

Token başına oranlar gpt-image-2 ile eşleşiyor; görüntü başına maliyet, kalite seviyesindeki token sayılarının değişmesi nedeniyle hala hareketli.

Ön Koşullar

• Ücretli kullanım katmanında bir OpenAI geliştirici hesabı. Görüntü uç noktaları, ödeme yöntemi eklemeyi gerektiren Katman 1 veya üzerini gerektirir; bir ChatGPT aboneliği sayılmaz. OpenAI API anahtarı kılavuzumuz, proje kapsamlı anahtarları kapsar.
• Python veya Node için resmi openai SDK'sı.
• Görüntü yanıtlarını önizlemenin bir yolu. curl base64 yazdırır, bu tekrar için zahmetlidir; Apidog, kod çözülmüş görüntüyü satır içinde işler ve son bölüm iş akışını oraya taşır.

Anahtarı bir kez dışa aktarın:

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

Curl ile bir görsel oluşturun

Önce Flare'ı kullanın; OpenAI'nin model sayfası bunu “çoğu uygulama için varsayılan seçim” olarak adlandırıyor.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

Yanıt, her görüntü için bir b64_json içeren bir data dizisi ve input_tokens ile output_tokens içeren bir usage nesnesi barındırır. usage'ı saklayın; elde ettiğiniz tek doğru maliyet sinyali odur. Görüntü oluşturma kılavuzundan parametre notları: output_format varsayılan olarak png'dir ve OpenAI “jpeg kullanmak png'den daha hızlıdır” der; output_compression (0-100) yalnızca jpeg ve webp için geçerlidir; background: "transparent" jpeg'de başarısız olur.

Python: oluştur, sonra referans görselle düzenle

SDK çağrısı, curl gövdesini yansıtır. b64_json'ı çözün ve baytları yazın.

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

Düzenlemeler, 2.5 modellerinin değerini ortaya koyduğu yerdir; lansman gönderisi, “yalnızca istediğiniz şeyi düzenlemede daha iyi olduklarını, diğer ayrıntıları aynı tuttuklarını” belirtiyor ve OpenAI, Sunburst'ı “düzenlemeler üzerinde daha sıkı kontrol” için konumlandırıyor. Düzenleme uç noktası çok parçalıdır: bir referans görsel, isteğe bağlı bir maske ve bir istem. Maskenin şeffaf olduğu yerlerde model yeniden boyar; diğer her yerde orijinalini korur.

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

mask'ı bırakın ve model, yalnızca istemden neyin değişeceğine karar verir. Referans görsel, 1M başına 8 dolardan görsel girdi tokenı olarak faturalandırılır; OpenAI, görüntü başına girdi tokenı sayısı yayınlamaz, bu nedenle usage.input_tokens'ı okuyun.

Node ve TypeScript: b64_json'ı diske yazın

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

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

Alias hareket halindeyken çıktıyı sabit tutmak için üretimde gpt-image-2.5-flare-2026-09-08'i sabitleyin.

Responses API: araç olarak görüntü oluşturma

Burada bir ana hat modeli isteminizi okur, onu düzeltir ve image_generation aracını çağırır. Araç tanımının içinde model'i ayarlayarak görüntü modelini seçersiniz; üst düzey model bir ana hat modeli olmalıdır ve OpenAI'nin araç belgeleri gpt-6-astra kullanır. Responses API kılavuzumuz istek yapısını kapsar. action alanı auto (varsayılan), generate veya edit alır; bir referans görüntü geçirdiğinizde ve onu yeniden yorumlamak yerine değiştirmek istediğinizde edit'i ayarlayın.

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

previous_response_id takibi, ilk görüntüyü bağlamda tutar, böylece “aynı sahne” dosyayı yeniden yüklemeye gerek kalmadan çözümlenir. Ana hat model tokenları, görüntü tokenlarının üzerine faturalandırılır ve istem yeniden yazımı, çıktıyı yalnızca istem metninden yeniden üretemeyeceğiniz anlamına gelir.

Kısmi görüntü akışı

Her iki API de partial_images (0 ila 3) kabul eder. Her kısmi görüntü 100 ek çıktı tokenı maliyetindedir, yani üç kısmi görüntü 300 token veya görüntü başına 0,009 dolar ekler. İlerleme gösteren bir kullanıcı arayüzü için değerlidir; toplu işte boşa harcanır.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

Tam olay tipi dizeleri görüntü oluşturma kılavuzundadır; son ek kontrolü, döngünün her iki API varyantında da çalışmasını sağlar. Akışlı olayları kod dışında incelemek için, AI API'lerinden SSE yanıtlarını test etme kılavuzumuza bakın.

Kullanımı oku ve tokenları dolara dönüştür

OpenAI'nin kendi uyarısı: “Eşit token oranları, görüntü başına eşit maliyet anlamına gelmez: token tüketimi modele ve kalite ayarlarına göre farklılık gösterebilir.” Görüntü oluşturma kılavuzundaki hesaplayıcı, fiyatlandırma sayfasındaki 1M başına 30 dolar oranla, yalnızca görüntü çıktı tokenları için şu tahminleri verir:

Yeniden etiketlemeye dikkat edin. 2.5'teki high, gpt-image-2'deki eski medium bütçesi olan 1.756 token kullanır; max, eski high bütçesi olan 7.024 token kullanır. Bir geçiş sırasında quality: "high"'ı korursanız, her görüntü eski orta bütçeyle yaklaşık 4 kat daha ucuz hale gelir; eski high bütçesi için max'a geçin. Flare vs Sunburst vs gpt-image-2 karşılaştırmamız tüm aylık hesaplamayı yapar.

Hesaplayıcı sayıları tahmindir. Gerçek maliyet yanıttan gelir:

OUTPUT_RATE = 30 / 1_000_000  # dollars per image output token
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} tokens = ${usd:.4f}")

İstek başına loglayın; OpenAI'ye göre, daha büyük kare olmayan bir boyut, daha küçük kare bir boyuttan daha az token üretebilir. Bir açık soru: fiyatlandırma sayfasının Toplu İş (Batch) sekmesi yalnızca gpt-image-2'yi listeler, bu nedenle 2.5 için Batch API desteğini doğrulanmamış olarak kabul edin.

Hatalar, oran sınırlamaları ve zaman aşımları

• 429 oran sınırlaması. Gecikmeli geri çekilin ve Retry-After'ı dikkate alın. 2.5 model sayfaları katman başına limitleri yayınlamıyor. Referans olarak, gpt-image-2 Katman 1'de dakikada 5 görüntü ve 100k TPM ile çalışır, Katman 5'e dakikada 250 görüntü ve 8M TPM'ye kadar ölçeklenir.
• insufficient_quota. Kredi yok veya hala ücretsiz katmanda. Faturalandırma ekleyin; yeniden denemeyin.
• Denetim reddetmeleri. İstem veya referans görüntü filtreyi tetikledi. Yeniden denemek yerine yeniden ifade edin; moderation: "low" eşiği gevşetir.
• Zaman aşımları. OpenAI, “Karmaşık istemlerin işlenmesi 2 dakikaya kadar sürebilir” diye belirtir. Müşteri zaman aşımlarını bunun üzerine ayarlayın; Sunburst tasarım gereği Flare'dan daha uzun çalışır.

Apidog'da Flare ve Sunburst'ı yan yana test edin

Görüntü istemleri üzerinde terminal yinelemesi, çıktıyı göremediğiniz için yavaştır ve yanlış bir quality değeri her gönderimde gerçek paraya mal olur. Apidog bir API istemcisi ve test platformudur: çağrıları gönderir ve yanıtları kontrol eder; OpenAI'nin sunucuları işleme yapar.

1. Anahtarı bir kez saklayın. OPENAI_API_KEY'i bir ortam değişkeni olarak ekleyin ve Authorization başlığında Bearer {{OPENAI_API_KEY}} olarak referans verin; anahtar asla kaydedilmiş bir isteğe düşmez.
2. İki ortam, bir istek. Her biri MODEL değişkenine sahip flare ve sunburst adında ortamlar oluşturun ve gövdede "model": "{{MODEL}}"'i ayarlayın. Geçiş yapın, yeniden gönderin ve görüntüleri ile usage'ı yan yana karşılaştırın. Düzenlemeler için, image ve mask dosya alanları olarak form-data gövdesi kullanın.
3. b64_json'ı bir son işlemcide çözün. Kısa bir betik data[0].b64_json'ı çeker, çözer ve dosyayı kaydeder, böylece her gönderim ham JSON'un yanında görüntülenebilir bir resim üretir.
4. Maliyeti onaylayın, sonra planlayın. usage.output_tokens'ın bir bütçenin altında kaldığını doğrulayın, örneğin high 1536x1024 işleme için 2.000 ve isteği zamanlanmış bir regresyon testi olarak çalıştırın. Birisi kaliteyi max'a yükseltirse veya bir anlık görüntü token sayılarını değiştirirse, test fatura gelmeden önce başarısız olur.

Apidog'u indirin, OpenAI anahtarınıza yönlendirin ve maliyet korumalı paylaşılan bir istem kütüphaneniz olsun.

Sıkça Sorulan Sorular

• 2.5'i kullanmak için gpt-image-2 kodumu değiştirmem gerekiyor mu? Model kimliğini değiştirin ve quality'yi yeniden kontrol edin. Uç noktalar, kimlik doğrulama ve yanıt şekli değişmedi, ancak high artık daha küçük bir token bütçesine eşleniyor. gpt-image-2 API kılavuzu hala eski modeli kapsıyor.
• API için Flare mı yoksa Sunburst mı? Flare ile başlayın. OpenAI, aynı token başına fiyatta gpt-image-2'den “%50 daha düşük gecikme süresi” ile onu varsayılan olarak konumlandırıyor. Ürün görselleri gibi düzenleme hassasiyetinin hızdan daha önemli olduğu durumlarda Sunburst'a geçin. Her ikisi de aynı hesaplayıcı token sayılarını paylaşır, bu nedenle takas zamanla ilgilidir, dolarla değil.
• Bu modelleri Sohbet Tamamlamalarında kullanabilir miyim? Hayır. Görüntü oluşturma, Görüntü API'sinde ve Responses API image_generation aracında yer alır. Sohbet Tamamlamaları bunu sunmaz.
• API aracılığıyla 2.5'i ücretsiz denemenin bir yolu var mı? Kalıcı bir ücretsiz API katmanı yok ve görüntü uç noktaları Katman 1 gerektirir. En ucuz gerçek yol, 196 token ile quality: "low"'dur, bu da 1024x1024 görüntü başına yaklaşık 0,006 dolara denk gelir. Tüketici uygulaması ayrı bir konudur; ChatGPT Images 2.5'i ücretsiz nasıl kullanacağınızı görün.

Sırada ne var

Curl çağrısıyla başlayın, usage.output_tokens'ı hesaplayıcı tablosuna göre onaylayın, ardından isteği görüntüyü görebileceğiniz bir istemciye taşıyın. Simon Willison'ın yazısı, Sunburst'ın bir konuyu eklerken bir grafiği sağlam tuttuğunu gösteriyor; bu düzenleme davranışını taahhüt etmeden önce kendi referans görselleriniz üzerinde test edin.