Async Image Generation API: İşler, Polling, Webhook'lar ve Yeniden Denemeler

Async bir image generation API, bir oluşturma isteği göndermenize, hemen bir iş tanımlayıcısı (job identifier) almanıza ve HTTP bağlantısını açık tutmak yerine tamamlanan görseli daha sonra almanıza olanak tanır. Bu eğitim; iş yaşam döngüsünü, ne zaman polling (anketleme) yapılıp ne zaman webhook kullanılacağını ve yavaş veya başarısız bir işin ürün deneyiminizi bozmaması için yeniden denemelerin (retries) nasıl tasarlanacağını kapsar.

Önemli Çıkarımlar

• Görsel oluşturma, istek-yanıt (request-response) tabanlı değil, iş (job) tabanlıdır; çünkü oluşturma gecikmesi (saniyelerden on saniyelere kadar) senkron bir bağlantıda tutulması için güvenilmezdir.
• Polling'i oluşturmak ve hata ayıklamak daha basittir; webhook'lar gecikmeyi ve istek hacmini azaltır ancak herkese açık bir uç nokta, imza doğrulaması ve yinelenen teslimatların idempotent (eşgüçlü) şekilde işlenmesini gerektirir.
• Yeniden deneme mantığı; gönderim hatalarını, takılı kalan işleri ve kaçırılan webhook teslimatlarını ayırt etmelidir; her biri farklı bir kurtarma yolu gerektirir.
• Tam uç nokta adları, alan adları ve webhook yükü şekilleri sağlayıcıya ve TokenLab'in kendi API yüzeyine göre farklılık gösterir. Yayına almadan önce her zaman docs.tokenlab.sh adresindeki güncel ayrıntıları doğrulayın.

Görsel Oluşturma API'leri Neden Async'tir?

Metin tamamlama API'leri genellikle aynı bağlantı üzerinden yanıt döndürebilir çünkü token oluşturma, stream edilebilecek kadar hızlıdır. Diffusion tabanlı veya autoregressive olsun, görsel oluşturma modelleri genellikle daha uzun sürer ve çözünürlüğe, model seçimine ve kuyruk derinliğine bağlı olarak daha değişken gecikmelere sahiptir. Senkron bir HTTP isteğini on saniyeler boyunca açık tutmak kırılgandır: istemci zaman aşımları, yük dengeleyici boşta kalma sınırları ve mobil ağ düşüşlerinin tümü, oluşturmak için zaten ödeme yaptığınız tamamlanmış bir sonucu kaybetme olasılığını artırır.

Görsel oluşturma sağlayıcılarında kullanılan standart model, bir iş modelidir: bir istek gönderirsiniz ve bir iş tanımlayıcısı ile başlangıç durumu (genellikle queued veya processing gibi) alırsınız. Ardından, iş terminal bir duruma ulaştığında ya bir durum uç noktasını poll edersiniz ya da bir webhook bildirimi alırsınız ve nihai görsel URL'lerini veya ikili verileri ayrı bir çağrıda getirirsiniz.

TokenLab, Nano Banana 2, Nano Banana Pro ve Nano Banana 2 Lite ailesi, GPT Image 2, Reve 2.0 ve MAI-Image-2.5 dahil olmak üzere birden fazla görsel modeline tek bir API yüzeyi üzerinden erişim sağlar. Güncel liste için görsel model dizinine ve TokenLab'e özgü iş uç noktası davranışı için async görsel oluşturma görevleri kılavuzuna bakın. Aşağıdaki genel model, hangi temel modeli çağırırsanız çağırın geçerlidir, ancak tam alan adları ve durum değerleri docs.tokenlab.sh adresinde belgelenmiştir ve bu makaleden varsaymak yerine orada doğrulanmalıdır.

İş Yaşam Döngüsü: Gönder, Poll Et, Al

Kavramsal düzeyde, bir async görsel işi üç aşamadan oluşur:

1. Gönder (Submit): Bir prompt ve parametreleri POST edin, bir iş ID'si ve başlangıç durumu alın.
2. Durumu kontrol et (Check status): İş ID'sini kullanarak bir GET uç noktasını poll edin veya bir webhook olayı bekleyin.
3. Çıktıyı al (Retrieve output): Durum terminal (succeeded veya failed) olduğunda, görsel URL'sini/URL'lerini veya hata detayını getirin.

İşte Python'da açıklayıcı bir polling modeli. Uç nokta yollarını ve alan adlarını yer tutucu olarak değerlendirin; bunu üretimde kullanmadan önce API belgelerindeki güncel TokenLab iş uç noktası şeklini doğrulayın.

import time
import requests

API_BASE = "https://api.tokenlab.sh/v1"  # docs.tokenlab.sh adresindeki güncel temel URL'yi doğrulayın
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit_image_job(prompt, model="nano-banana-2"):
    resp = requests.post(
        f"{API_BASE}/images/jobs",
        headers=HEADERS,
        json={"prompt": prompt, "model": model, "idempotency_key": generate_key()},
    )
    resp.raise_for_status()
    return resp.json()["job_id"]

def poll_job(job_id, max_wait_seconds=120, interval=2, backoff=1.5):
    waited = 0
    while waited < max_wait_seconds:
        resp = requests.get(f"{API_BASE}/images/jobs/{job_id}", headers=HEADERS)
        resp.raise_for_status()
        data = resp.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
        waited += interval
        interval = min(interval * backoff, 15)
    raise TimeoutError(f"Job {job_id} did not complete within {max_wait_seconds}s")

job_id = submit_image_job("a studio product shot on white background")
result = poll_job(job_id)
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
else:
    print("job failed:", result.get("error"))

Gönderim çağrısındaki idempotency_key önemlidir: iş oluşturulduktan sonra ancak istemciniz iş ID'sini almadan önce bir ağ hatası oluşursa, aynı anahtarla gönderim çağrısını yeniden denemek, yinelenen bir oluşturma işlemi yaratmak yerine mevcut işi döndürmelidir. TokenLab'in iş uç noktasının idempotency anahtarlarını destekleyip desteklemediğini ve nasıl desteklediğini güncel belgelerden doğrulayın, çünkü bu sağlayıcılar arasında yaygın ancak evrensel olmayan bir modeldir.

Polling vs. Webhook'lar: Takaslar

Her iki yaklaşım da geçerlidir; doğru seçim trafik modelinize ve altyapınıza bağlıdır.

Polling'in uygulanması ve yerel olarak test edilmesi daha basittir, herkese açık bir uç nokta gerektirmez ve birkaç saniyelik ek gecikmenin önemli olmadığı düşük hacimli veya toplu iş yükleri için gayet iyi çalışır. Dezavantajları, poll aralığınıza eşit bir gecikme tabanı ve uzun süren işlerde çok agresif poll yaparsanız gereksiz istek hacmidir.

Webhook'lar, bir iş durum değiştirdiğinde sunucunuza bir bildirim gönderir; bu da gecikmeyi düşürür ve boşa giden durum kontrol çağrılarını azaltır. Maliyeti operasyoneldir: herkese açık, ulaşılabilir bir HTTPS uç noktasına, yükün gerçekten sağlayıcıdan geldiğini doğrulamak için imza doğrulamasına ve yinelenen veya sıra dışı teslimatların işlenmesine ihtiyacınız vardır.

OpenAI'ın webhook olayları referans belgeleri, asenkron işlemler için bu modelin genel şeklini açıklar: uç noktanız bir tür ve nesne tanımlayıcısı içeren bir olay alır ve önerilen uygulama, webhook yükünü nihai doğruluk kaynağı olarak güvenmek yerine, kaynağın mevcut durumunu API aracılığıyla getirmek için bir bildirim olarak değerlendirmektir. Bu "pull-after-push" (itmeden sonra çekme) modeli, hangi görsel sağlayıcısını entegre ederseniz edin benimsemeye değerdir, çünkü bir webhook yükü kesilirse, gecikirse veya birden fazla kez teslim edilirse sizi korur.

Webhook'ları Güvenle Uygulama

Görsel işi tamamlama için webhook'ları seçerseniz, aşağıdaki uygulamalar sessiz hata olasılığını azaltır:

• İmzayı doğrulayın. İşlemeden önce gelen her webhook isteğindeki imzayı doğrulayın. Eşleşmeyen her şeyi reddedin ve yanlış yapılandırılmış bir sırrı hızlıca tespit edebilmek için reddetmeleri normal trafikten ayrı olarak günlüğe kaydedin.
• Hızlı yanıt verin, sonra işleyin. Doğruladığınız anda 200 durumuyla webhook'u onaylayın, ardından gerçek işi (görseli getirme, depolamaya yazma, kullanıcınızı bilgilendirme) bir arka plan işine veya kuyruğuna devredin. Sağlayıcılar, zamanında bir 2xx yanıtı alamazlarsa genellikle webhook teslimatını yeniden denerler, bu da işleyiciniz yavaş ve senkron ise yinelenen işleme neden olabilir.
• İş ID'sine göre tekilleştirin. İşlenmiş iş ID'lerini (veya olayın bir hash'ini) saklayın, böylece yeniden denenen bir teslimat bir bildirimi yeniden oluşturmaz veya bir dosya yazma işlemini yeniden işlemez.
• Kaynağı yeniden getirin. Yukarıda açıklanan "pull-after-push" modeliyle tutarlı olarak, gömülü çıktı URL'lerine nihai olarak güvenmek yerine webhook yükündeki iş ID'sini kullanarak kaynağı yeniden getirin.

Minimal bir işleyici taslağı:

from flask import Flask, request, abort

app = Flask(__name__)
processed_job_ids = set()  # üretimde gerçek bir depo kullanın

@app.route("/webhooks/image-jobs", methods=["POST"])
def handle_webhook():
    if not verify_signature(request):
        abort(401)

    event = request.get_json()
    job_id = event.get("job_id") or event.get("data", {}).get("id")
    if job_id in processed_job_ids:
        return "", 200  # zaten işlendi, onayla ve atla

    enqueue_background_task("fetch_and_store_image", job_id)
    processed_job_ids.add(job_id)
    return "", 200

Görsel işi tamamlama için kullanılan tam webhook olay adlarını, yük yapısını ve imza başlığını güncel sağlayıcı belgelerine ve ayrıca docs.tokenlab.sh adresinde açıklandığı gibi TokenLab'in kendi webhook desteğine göre doğrulayın, çünkü bu ayrıntılar sağlayıcıya özeldir ve değişebilir.

Yeniden Deneme Tasarımı: Üç Hata Sınıfı

Async görsel işleri üç farklı şekilde başarısız olur ve her birinin kendi işlenmesine ihtiyacı vardır:

1. Gönderim hataları: Bir iş oluşturmak için yapılan POST, 4xx veya 5xx döndürür. 5xx ve ağ hataları için, aynı idempotency anahtarını yeniden kullanarak üstel geri çekilme (exponential backoff) ve jitter ile yeniden deneyin, böylece yinelenen işler oluşturmazsınız. 4xx hataları (hatalı prompt, geçersiz model, kota aşıldı) için, isteği değiştirmeden yeniden denemek yine başarısız olacaktır; bunun yerine hatayı çağırana iletin.
2. Takılı kalan işler: Bir iş, beklenen oluşturma süresinin çok ötesinde terminal olmayan bir durumda kalır. Model başına maksimum bir bekleme eşiği belirleyin (oluşturma süresi modele ve çözünürlüğe göre değişir) ve sağlayıcı henüz resmi olarak başarısız olarak işaretlememiş olsa bile, bu süreyi aşan işleri uygulamanızın amaçları doğrultusunda başarısız kabul edin. Bunları ayrı olarak günlüğe kaydedin, çünkü artan takılı kalan iş oranı genellikle sağlayıcı tarafında bir olaya işaret eder.
3. Kaçırılan webhook teslimatları: Uç noktanız kapalıydı veya teslimat düşürüldü ve hiçbir olay gelmedi. Bu yüzden, webhook öncelikli bir tasarımda bile polling yedeğini tutmaya değer: terminal durumu olmayan birkaç dakikadan eski herhangi bir işin durumunu kontrol eden periyodik bir tarama, webhook'u sessizce gelmeyen işleri yakalar.

Karar Kontrol Listesi

Bir görsel oluşturma özelliği için iş tamamlamanın nasıl bağlanacağına karar verirken bu kontrol listesini kullanın.

Senaryo	Önerilen yaklaşım	Neden
Düşük hacimli, dahili araç veya toplu iş betiği	Polling	Oluşturması en basit; herkese açık uç nokta gerekmez
Gecikmenin önemli olduğu kullanıcıya dönük özellik	Webhook'lar, polling yedek taraması ile	Daha düşük gecikme; yedek, kaçırılan teslimatları yakalar
Yüksek iş hacmi (günde binlerce)	Webhook'lar	Aşırı durum kontrolü istek hacminden kaçınır
Herkese açık HTTPS uç noktası sunamama	Polling	Webhook'lar ulaşılabilir bir alıcı gerektirir
Sıkı yinelenen önleme ihtiyacı	Gönderimde idempotency anahtarları, alımda iş ID'sinde tekilleştirme	Yeniden denenen gönderimlere ve yinelenen webhook teslimatlarına karşı korur
Tek bir pipeline'da birden fazla görsel modeli	Kendi katmanınızda iş durumunu ve hata işlemeyi normalleştirin	Temel sağlayıcılar (bkz. görsel model karşılaştırması) aynı durum taksonomilerini paylaşmaz

Sınırlamalar

Bu makale, async görsel iş API'leri için genel bir modeli açıklar ve yukarıda belirtilenlerin ötesinde TokenLab veya herhangi bir belirli temel model sağlayıcısı için tam uç nokta yollarını, alan adlarını, zaman aşımı değerlerini veya webhook olay adlarını iddia etmez. İş durumu kelime dağarcıkları, retry-after başlıkları ve webhook imza şemaları sağlayıcılar arasında farklılık gösterir ve zamanla değişebilir; bu makaledeki kodu kopyala-yapıştır üretim kodu olarak değil, açıklayıcı olarak değerlendirin ve yayına almadan önce docs.tokenlab.sh adresindeki güncel istek ve yanıt şekillerini doğrulayın. Bu makale, herhangi bir belirli model için fiyatlandırmayı, hız sınırlarını veya verimlilik garantilerini kapsamaz.

SSS

Her zaman polling yerine webhook kullanmalı mıyım? Hayır. Webhook'lar daha yüksek operasyonel maliyetle gecikmeyi ve istek hacmini azaltır. Düşük hacimli veya dahili kullanım durumları için polling genellikle daha basit ve eşit derecede güvenilir bir seçimdir. Birçok üretim sistemi, webhook'ları birincil yol olarak kullanırken, periyodik bir polling taramasını yedek olarak kullanır.

Yeniden denemelerde yinelenen görsel oluşturmalardan nasıl kaçınırım? İş gönderim isteğinde bir idempotency anahtarı kullanın, böylece bir ağ hatasından sonra yeniden denenen POST, yeni bir tane oluşturmak yerine mevcut işi döndürür. Buna güvenmeden önce sağlayıcınızın iş oluşturma uç noktasının bunu destekleyip desteklemediğini doğrulayın.

İş tamamlandığında webhook uç noktam kapalıysa ne olur? Davranış sağlayıcıya bağlıdır; bazıları bir süre teslimatı yeniden dener, diğerleri yeniden teslimatı garanti etmez. Terminal durumu olmayan birkaç dakikadan eski işler için periyodik bir polling taraması, sağlayıcının yeniden deneme politikasından bağımsız olarak pratik bir güvenlik önlemidir.

Bir görsel oluşturma özelliği oluşturuyorsanız ve tek bir API'de birden fazla model arasında iş tabanlı erişimi karşılaştırmak istiyorsanız, görsel model dizinini ve async görsel oluşturma görevleri kılavuzunu inceleyin, ardından yapınız için güncel uç nokta ve webhook ayrıntılarını doğrulamak üzere TokenLab'in API belgeleriyle Başlayın.