> ## 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. # Kuyruk 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: ```bash theme={null} 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: ```json theme={null} { "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ı ```bash theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```json theme={null} { "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: ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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.