TokenLab'de GPT Image Edit API: Doğru Endpoint ve Görsel Giriş Biçimleri

Görsel düzenleme, bir yapay zekâ ürün yüzeyinin en zorlu kısımlarından biridir: kullanıcı bir fotoğraf yükler, bir değişiklik tanımlar ve bir sonuç bekler. Birden fazla kaynak görsel, büyük bir tuval veya daha ağır bir prompt kullanan düzenlemeler, tipik bir eşzamanlı HTTP çağrısının rahatça izin verdiğinden daha uzun sürer. Bu kılavuz, doğru TokenLab endpoint'ini, desteklenen iki görsel giriş biçimini, çoklu görsel düzenlemelerini ve yavaş istekler için asenkron yolu ele almaktadır.

Endpoint

Görsel düzenleme POST /v1/images/edits adresinde bulunur — çoğul olan edits ifadesine dikkat edin. (Yaygın bir hata, belgelenmiş yol olmayan /images/edit yazmaktır.)

Endpoint iki istek biçimini destekler:

• OpenAI uyumlu bir multipart/form-data yükleme akışı.
• Desteklenen görselden-görsele (image-to-image) aileleri için image_url, image_urls veya resmi images[] referansları sağlayan bir JSON isteği.

İstek ve yanıt alanlarının tamamı Edit Image API reference sayfasında belgelenmiştir.

gpt-image-2 burada neleri kabul eder

• Multipart image yüklemeleri.
• JSON image_url veya image_urls.
• Her bir nesnenin image_url veya file_id değerlerinden tam olarak birini içerdiği resmi images[] referansları.
• İstek başına en fazla 16 kaynak görsel.

Kod yazmadan önce bilinmesi gereken birkaç kısıtlama:

• gpt-image-2 düzenlemeleri resolution kabul etmez; çıktı boyutları için size kullanın (16'nın katları olan boyutlarla, en uzun kenarı en fazla 3840px ve uzun/kısa kenar oranı en fazla 3:1 olacak şekilde auto ya da WIDTHxHEIGHT).
• background, auto veya opaque kabul eder; transparent desteklenmez.
• input_fidelity, gpt-image-2 için desteklenen alanların bir parçası değildir; bunu göndermek 400 unsupported_parameter döndürür.
• JSON istekleri için image_url, image_urls veya images seçeneklerinden tam olarak birini belirtin. Her bir images[] nesnesi image_url veya file_id değerlerinden tam olarak birini içermelidir. file_id değerleri önceden /v1/files aracılığıyla oluşturulmalıdır.
• Nano Banana referans görseli istekleri /v1/images/edits üzerinde değil, operation: "image-to-image" ve image_urls ile /v1/images/generations üzerinde yer alır.

Multipart yüklemeleri ve JSON görsel referansları karşılaştırması

Her ikisi de gpt-image-2 için çalışır. Görsel baytlarınızın halihazırda bulunduğu yere uygun olanı seçin.

Multipart — dosya ister bir kullanıcı yüklemesinden ister üretilmiş bir varlıktan olsun, uygulamanın elinde bulunduğunda bunu kullanın. Birden fazla kaynak göndermek için image alanını tekrarlayın. Dosyalar PNG, JPEG veya WebP olmalı ve her biri en fazla 50 MiB büyüklüğünde olmalıdır.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

JSON görsel URL'leri — görseller halihazırda herkese açık bir URL'de bulunduğunda veya bunları daha önceki bir TokenLab isteğinde üretip zaten bir URL'ye sahip olduğunuzda bunu kullanın.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

Uzak URL'ler gömülü kimlik bilgileri veya parçalar (fragment) içermeyen, herkese açık http/https bağlantıları olmalı; localhost, özel veya ayrılmış IP aralıklarına çözümlenmemelidir. TokenLab baytları getirir ve modele multipart image parçaları olarak iletir. Görsel başına sınır 50 MiB'dir; tek bir istekte URL ile getirilen görseller için toplam sınır 200 MiB'dir; getirme zaman aşımı 30 saniyedir; en fazla 3 yönlendirme takip edilir.

Çoklu görsel düzenlemeleri ve asenkron yoklama (polling)

Çoklu görsel düzenlemeleri, async: true kullanımı için en belirgin durumdur. Karmaşık bir talimat kümesiyle birden fazla görseli eşzamanlı bir çağrı üzerinden göndermek, modelin ihtiyaç duyduğu süre boyunca bir bağlantıyı açık tutmak anlamına gelir. Bunun yerine bir görev almak için gpt-image-2 üzerinde (ve resmi FLUX/BFL düzenleme modellerinde) async: true olarak ayarlayın:

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

Dönen poll_url adresini yoklayın veya alternatif olarak GET /v1/tasks/{task_id} kullanın. Durumlar pending, processing, completed ve failed şeklindedir. Tamamlanan bir görsel görevi data[].url döndürür. 3–5 saniyede bir kontrol etmek yeterlidir; yoklamaya devam etmek yerine nihai bir duruma ulaşıldığında durun.

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Asenkron düzenleme görevleri, istenen response_format ne olursa olsun nihai görsel URL'lerini döndürür. Ham b64_json formatına ihtiyacınız varsa eşzamanlı bir istek kullanın.

Faturalandırma, görev oluşturulduğunda tahmini tutarı rezerve edebilir; tamamlanan bir görev fiili kullanıma göre faturalandırılır ve başarısız olan ya da zaman aşımına uğrayan bir görev rezervasyonu serbest bırakır veya iade eder. Tam yaşam döngüsü için Async jobs and polling sayfasına, yanıt alanları için ise Get Image Status sayfasına bakın.

Her modun ne zaman kullanılacağı

Şu durumlarda async: true kullanın:

• Tek bir istekte birden fazla kaynak görsel gönderiyorsanız.
• Prompt veya talimat kümeniz, üretim süresi öngörülemeyecek kadar karmaşıksa.
• Düzenlemeleri canlı bir kullanıcı isteği yerine bir arka plan işinde, kuyrukta veya toplu işlemde (batch) çalıştırıyorsanız.

Şu durumlarda eşzamanlı kalın:

• Kısa bir prompt ile tek bir görsel düzenlemesi yapıyorsanız.
• İstemciniz yoklama yapmak yerine hızlıca hata almayı (fail fast) tercih ediyorsa.

Eşzamanlı çağrılar için HTTP istemci zaman aşımınızı en az 120s olarak ayarlayın; yüksek çözünürlüklü veya yüksek kaliteli istekler bir dakikaya yakın veya daha uzun sürebilir. Oluşturma yanıtı yine de status: "pending", task_id veya poll_url ile dönerse, verilen yoklama akışına geçin.

Beklenmesi gereken giriş hataları

Uzak görsel getirme hataları, üretim başlamadan önce giriş hataları olarak döndürülür. Ulaşılamayan URL'ler, zaman aşımları, 403/404 yanıtları, özel veya dahili ana bilgisayarlar, URL'deki kimlik bilgileri veya parçalar, görsel olmayan içerikler, desteklenmeyen formatlar ve boyut sınırı ihlalleri 400 veya 413 döndürür ve sorunlu image_url veya image_urls[n] öğesini belirtir. Özel veya başlık korumalı varlıklar için multipart image dosyalarını doğrudan yükleyin ya da /v1/files referansları oluşturup bunları images[].file_id olarak iletin.

xAI Grok Imagine görsel düzenleme modelleri (örneğin grok-imagine-image ve grok-imagine-image-quality) aynı giriş alanlarını kullanır ancak kaynak görselleri 3 ile sınırlar; bundan fazlası 400 too_many_images döndürür.

Entegrasyon kontrol listesi

• POST /v1/images/edits endpoint'ini hedefleyin ve model parametresini açıkça gönderin.
• Görsellerinizin halihazırda bulunduğu yere göre multipart yüklemelerini veya JSON referanslarını seçin.
• JSON isteklerinde image_url, image_urls veya images[] seçeneklerinden tam olarak birini gönderin; her bir images[] girdisinde image_url veya file_id seçeneklerinden tam olarak biri bulunmalıdır.
• Çoklu görsel veya ağır düzenlemeler için async: true kullanın; görev completed veya failed durumuna ulaşana kadar dönen poll_url adresini yoklayın.
• Eşzamanlı istekler için istemci zaman aşımlarını en az 120 saniyeye ayarlayın ve poll_url izleyerek olası bir pending yanıtını ele alın.
• Bir istemci zaman aşımı durumunda, mükerrer ücretlendirmeleri önlemek için oluşturma isteğini yeniden denemeden önce bir görevin oluşturulup oluşturulmadığını kontrol edin.

Başlarken

Güncel görsel modellerini görmek için GET /v1/models?recommended_for=image sorgusu yapın, ardından bir istek göndermeden önce desteklenen işlemlerini ve istek alanlarını doğrulamak için bir modelin detay sayfasını açın. Düzenleme endpoint'ini kendi görsellerinizle test etmek için konsoldan bir API anahtarı oluşturun.