Kuyruk - Sunra.ai

AI uygulamalarında tipik olan ve birkaç saniyeden uzun süren istekler için bir kuyruk sistemi geliştirdik. Bu sistem, trafik artışlarını yönetmek, gerekirse istekleri iptal etmek ve isteğinizin kuyruktaki durumunu izlemek için size ayrıntılı kontrol sunar. Ayrıca, uzun süren HTTP isteklerini yönetme ihtiyacını da ortadan kaldırır.

Kuyruk Uç Noktaları

Tüm kuyruk özelliklerine aşağıdaki uç noktalar üzerinden erişebilirsiniz:

Uç Nokta	Yöntem	Açıklama
api.sunra.ai/v1/queue/{model-id}	POST	Kuyruğa bir istek ekler
api.sunra.ai/v1/queue/requests/{request_id}/status	GET	Bir isteğin durumunu alır
api.sunra.ai/v1/queue/requests/{request_id}/status/stream	GET	Tamamlanana kadar durumu yayınlar
api.sunra.ai/v1/queue/requests/{request_id}	GET	Bir isteğin yanıtını getirir
api.sunra.ai/v1/queue/requests/{request_id}/cancel	PUT	Bir isteği iptal eder

Örneğin, curl kullanarak bir istek göndermek ve kuyruğa eklemek için:

curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Renkli evler, çamaşırların sallandığı ve pencerelerde uyuyan kedilerin olduğu Studio Ghibli tarzı sahil kasabası."}'

İşte request_id’yi içeren örnek bir yanıt:

{
  "request_id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/cancel"
}

Yük, request_id’yi içerir ve durumu kontrol etmek, iptal etmek veya yanıtı almak için URL’ler sağlar, bu da ek uç nokta geliştirmeden iş akışınızı kolaylaştırır.

İstek Durumu

İsteğinizin ilerlemesini izlemek için, benzersiz istek kimliğinizle sağlanan uç noktayı kullanın. Bu, durumu, kuyruk konumunu izlemenize veya hazır olduğunda yanıtı almanıza olanak tanır.

Uç Nokta Kullanımı

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

Örnek Yanıt

İsteğiniz kuyruktayken, şöyle bir yanıt alırsınız:

{
  "status": "IN_QUEUE",
  "metrics": {},
  "queue_position": 0,
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/cancel"
}

Olası Durumlar

İsteğiniz üç durumdan birinde olabilir:

IN_QUEUE: İsteğin işlenmeyi beklediğini gösterir.
- queue_position: Kuyruktaki yerinizi gösterir.
- response_url: İşlem tamamlandığında yanıtı almak için URL.
IN_PROGRESS: İstek şu anda işleniyor.
- logs: İşlem adımlarını gösteren ayrıntılı günlükler (etkinleştirilmişse).
- response_url: Son yanıtın bulunacağı yer.
COMPLETED: İşlem tamamlandı.
- logs: Tüm süreci detaylandıran günlükler.
- response_url: Tamamlanmış yanıtınıza doğrudan bağlantı.

Günlükleri Etkinleştirme

Günlükler, istek işleme hakkında bilgi sağlar. Varsayılan olarak devre dışıdırlar ancak bir sorgu parametresiyle etkinleştirilebilirler:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1

Her günlük girişi şunları içerir:

message: Olayın açıklaması.
level: Önem derecesi (örneğin, INFO, ERROR).
source: Günlüğün kaynağı.
timestamp: Günlüğün oluşturulduğu zaman.

Gerçek Zamanlı İzleme

Sürekli güncellemeler için akış uç noktasını kullanın:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream

Bu, istek tamamlanana kadar text/event-stream formatında gerçek zamanlı durum güncellemeleri sağlar.

Webhooks

Polling yerine bildirim almayı tercih ederseniz, istek gönderirken bir webhook sorgu parametresi geçirin. Sunra, istek terminal duruma ulaştığında nihai sonucu bu URL’ye POST eder, böylece bağlantıyı açık tutmanıza veya polling planlamanıza gerek kalmaz.

Webhook’ları Etkinleştirme

Gönderim uç noktasına URL kodlanmış bir webhook sorgu parametresi ekleyin:

curl -X POST \
  "https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image?webhook=https%3A%2F%2Fexample.com%2Fsunra-webhook" \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Studio Ghibli tarzında, renkli evleri, rüzgârda dalgalanan çamaşırları ve pencere pervazlarında uyuyan kedileri olan bir sahil kasabası."}'

Webhook URL’sini URL olarak kodlayın (örn. https%3A%2F%2F...) ve Sunra’nın bu adrese erişebildiğinden emin olun; HTTPS şiddetle önerilir. Gönderim yanıtı değişmez — yine bir request_id ve aynı status/cancel/response URL’lerini alırsınız.

Webhook Ne Zaman Tetiklenir

Sunra, webhook’unuzu yalnızca terminal olaylarda çağırır:

succeeded — istek tamamlandı ve çıktı yükte yer alır.
failed — istek başarısız oldu ve hata ayrıntıları yükte yer alır.

Ara durumlar (IN_QUEUE, IN_PROGRESS) webhook’u tetiklemez. İlerleme güncellemeleri de gerekiyorsa, webhook’u yukarıda açıklanan akış veya polling uç noktalarıyla birlikte kullanın.

İstek Formatı

Sunra webhook URL’nize aşağıdaki başlıklarla POST isteği gönderir:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Sunra-AI-Webhook/1.0`

Uç noktanız 5 saniye içinde bir 2xx durum kodu ile yanıt vermelidir. Hızlıca onay verin ve ağır işleri arka plan görevine devredin — yavaş yanıtlar başarısız sayılır ve yeniden denemeleri tetikler.

Yük

Başarılı bir olay:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "Studio Ghibli tarzında bir sahil kasabası..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Başarısız bir olay output yerine error içerir. error’ın tam içeriği başarısızlık türüne göre değişir — aşağıdaki örnek yaygın bir biçimi gösterir:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "Studio Ghibli tarzında bir sahil kasabası..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "İnsan tarafından okunabilir hata mesajı"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Alan	Açıklama
`id`	Gönderim sırasında dönen `request_id`. Yeniden denemeleri tekilleştirmek için kullanın.
`object`	Her zaman `"prediction"`.
`model`	Model sahibi ve adı (örn. `black-forest-labs/flux-1.1-pro`).
`model_endpoint`	Uç nokta etiketi (örn. `text-to-image`).
`status`	`"succeeded"` veya `"failed"`.
`input`	Gönderdiğiniz orijinal istek gövdesi.
`output`	`succeeded` olduğunda mevcut. Sonuç uç noktasının döndürdüğü yanıt gövdesinin aynısıdır.
`error`	`failed` olduğunda mevcut. Başarısızlığı tanımlayan bir nesne; yapısı başarısızlık türüne bağlıdır.
`created_at`	İstek oluşturulduğunda ISO 8601 zaman damgası.
`completed_at`	İstek terminal duruma ulaştığında ISO 8601 zaman damgası.

Yeniden Deneme Davranışı

Webhook teslimi en-az-bir-kere tipindedir. Uç noktanız zaman aşımına uğrarsa (5 sn) veya 2xx dışı bir durum kodu döndürürse, Sunra üstel geri çekilme ile yeniden dener — en fazla 3 yeniden deneme, 10 saniyeden başlayan ve 30 saniye ile sınırlı gecikmelerle. Son denemeden sonra, başarısızlık günlüğe kaydedilir ve daha fazla deneme yapılmaz. Yeniden denemeler aynı olayı birden fazla kez teslim edebileceğinden, işleyiciniz idempotent olmalıdır — tekilleştirme anahtarı olarak id alanını kullanın.

En İyi Uygulamalar

HTTPS kullanın ve trafiğin beklediğiniz uç noktaya ulaştığını doğrulayın.
Hemen 2xx ile yanıt verin ve yükü asenkron olarak işleyin.
Teslimi en-az-bir-kere olarak ele alın ve id ile tekilleştirin.
Terminal olaydan önce ilerleme güncellemelerine ihtiyacınız varsa, webhook’ları polling veya akış uç noktalarıyla birleştirin.

İstekleri İptal Etme

İsteğiniz hala kuyruktaysa, şununla iptal edebilirsiniz:

curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

Yanıtları Alma

İsteğiniz COMPLETED olduğunda, yanıtı şununla alın:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}

Bu uç nokta, inceleme için günlükler de sağlar.

Sunra İstemcisi ile Basitleştirilmiş Entegrasyon

Sunra istemcisi, durum takibini otomatikleştirir ve Sunra işlevleriyle uygulama geliştirmeyi basitleştirir.

Hız Sınırları

Adil kullanımı ve sistem kararlılığını sağlamak için API uç noktalarımız aşağıdaki hız sınırlarına tabidir:

Uç Nokta Türü	Hız Sınırı	Patlama Sınırı
Kuyruğa Gönder	10 istek/saniye	100 istek/dakika
Diğer Tüm Uç Noktalar	100 istek/saniye	1,800 istek/dakika

Bu sınırları aşarsanız, bir 403 Yasak yanıtı alırsınız. Bu durumları ele almak için üstel geri çekilme ile bir yeniden deneme mekanizması uygulamanızı öneririz.

​Kuyruk Uç Noktaları

​İstek Durumu

​Uç Nokta Kullanımı

​Örnek Yanıt

​Olası Durumlar

​Günlükleri Etkinleştirme

​Gerçek Zamanlı İzleme

​Webhooks

​Webhook’ları Etkinleştirme

​Webhook Ne Zaman Tetiklenir

​İstek Formatı

​Yük

​Yeniden Deneme Davranışı

​En İyi Uygulamalar

​İstekleri İptal Etme

​Yanıtları Alma

​Sunra İstemcisi ile Basitleştirilmiş Entegrasyon

​Hız Sınırları