Documentation Index
Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 |
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ı."}'
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"
}
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
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
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ı."}'
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.
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 |
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"
}
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}
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 |
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.
