कतार

AI अनुप्रयोगों में आम तौर पर कुछ सेकंड से अधिक समय लेने वाले अनुरोधों के लिए, हमने एक कतार प्रणाली विकसित की है। यह प्रणाली आपको ट्रैफिक उछाल को प्रबंधित करने, जरूरत पड़ने पर अनुरोध रद्द करने और कतार में अपने अनुरोध की स्थिति की निगरानी करने के लिए सूक्ष्म नियंत्रण प्रदान करती है। यह लंबे समय तक चलने वाले HTTP अनुरोधों को संभालने की आवश्यकता को भी समाप्त करता है।

कतार समापन बिंदु

आप निम्नलिखित समापन बिंदुओं के माध्यम से सभी कतार सुविधाओं तक पहुंच सकते हैं:

समापन बिंदु	विधि	विवरण
api.sunra.ai/v1/queue/{model-id}	पोस्ट	कतार में एक अनुरोध जोड़ता है
api.sunra.ai/v1/queue/requests/{request_id}/status	पाना	एक अनुरोध की स्थिति प्राप्त करता है
api.sunra.ai/v1/queue/requests/{request_id}/status/stream	पाना	पूरा होने तक स्थिति को स्ट्रीम करता है
api.sunra.ai/v1/queue/requests/{request_id}	पाना	एक अनुरोध की प्रतिक्रिया प्राप्त करता है
api.sunra.ai/v1/queue/requests/{request_id}/cancel	डालना	एक अनुरोध रद्द करता है

उदाहरण के लिए, कर्ल का उपयोग करके एक अनुरोध सबमिट करने और उसे कतार में जोड़ने के लिए:

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": "रंगीन घरों, फहराती लॉन्ड्री और खिड़कियों पर सो रही बिल्लियों वाला एक स्टूडियो घिबली-प्रेरित समुद्र तटीय शहर।"}'

यहां request_id सहित एक नमूना प्रतिक्रिया है:

{
  "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 शामिल है और स्थिति की जाँच, रद्द करने या प्रतिक्रिया प्राप्त करने के लिए URL प्रदान करता है, जिससे अतिरिक्त समापन बिंदु विकास के बिना आपके वर्कफ़्लो को सुव्यवस्थित किया जा सके।

अनुरोध की स्थिति

अपने अनुरोध की प्रगति की निगरानी के लिए, अपने अद्वितीय अनुरोध आईडी के साथ प्रदान किए गए समापन बिंदु का उपयोग करें। यह आपको स्थिति, कतार की स्थिति को ट्रैक करने या प्रतिक्रिया तैयार होने पर उसे प्राप्त करने की अनुमति देता है।

समापन बिंदु उपयोग

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

उदाहरण प्रतिक्रिया

जब आपका अनुरोध कतार में होता है, तो आपको इस तरह की प्रतिक्रिया मिलेगी:

{
  "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"
}

संभावित स्थितियाँ

आपका अनुरोध तीन में से एक स्थिति में हो सकता है:

IN_QUEUE: इंगित करता है कि अनुरोध संसाधित होने की प्रतीक्षा कर रहा है।
- queue_position: कतार में आपका स्थान दिखाता है।
- response_url: प्रसंस्करण पूरा होने पर प्रतिक्रिया प्राप्त करने के लिए URL।
IN_PROGRESS: अनुरोध वर्तमान में संसाधित किया जा रहा है।
- logs: प्रसंस्करण चरणों को दर्शाने वाले विस्तृत लॉग (यदि सक्षम हो)।
- response_url: जहां अंतिम प्रतिक्रिया उपलब्ध होगी।
COMPLETED: प्रसंस्करण समाप्त हो गया है।
- logs: पूरी प्रक्रिया का विवरण देने वाले लॉग।
- response_url: आपकी पूरी की गई प्रतिक्रिया का सीधा लिंक।

लॉग सक्षम करना

लॉग अनुरोध प्रसंस्करण में अंतर्दृष्टि प्रदान करते हैं। वे डिफ़ॉल्ट रूप से अक्षम होते हैं लेकिन एक क्वेरी पैरामीटर के साथ सक्षम किए जा सकते हैं:

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

प्रत्येक लॉग प्रविष्टि में शामिल हैं:

message: घटना का विवरण।
level: गंभीरता (जैसे, INFO, ERROR)।
source: लॉग की उत्पत्ति।
timestamp: लॉग उत्पन्न होने का समय।

रीयल-टाइम निगरानी

निरंतर अपडेट के लिए, स्ट्रीमिंग एंडपॉइंट का उपयोग करें:

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

यह अनुरोध पूरा होने तक text/event-stream प्रारूप में रीयल-टाइम स्थिति अपडेट प्रदान करता है।

Webhooks

यदि आप पोलिंग के बजाय सूचित किया जाना पसंद करते हैं, तो अनुरोध सबमिट करते समय एक webhook क्वेरी पैरामीटर पास करें। जैसे ही अनुरोध अंतिम स्थिति में पहुंचता है, Sunra उस URL पर अंतिम परिणाम POST करेगा, इसलिए आपको कोई कनेक्शन खुला रखने या पोलिंग शेड्यूल करने की आवश्यकता नहीं है।

Webhooks सक्षम करना

सबमिट एंडपॉइंट में URL-एन्कोडेड webhook क्वेरी पैरामीटर जोड़ें:

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": "स्टूडियो जिबली से प्रेरित एक समुद्री किनारे का शहर रंगीन घरों, हवा में लहराते कपड़ों, और खिड़कियों पर सोती बिल्लियों के साथ।"}'

Webhook URL को URL-एन्कोडेड (जैसे https%3A%2F%2F...) करें और सुनिश्चित करें कि Sunra उस तक पहुँच सके; HTTPS की पुरज़ोर सिफारिश की जाती है। सबमिट प्रतिक्रिया अपरिवर्तित रहती है — आपको अभी भी request_id और वही status/cancel/response URL प्राप्त होते हैं।

Webhook कब फायर होता है

Sunra आपके webhook को केवल अंतिम घटनाओं पर कॉल करता है:

succeeded — अनुरोध समाप्त हुआ और आउटपुट पेलोड में शामिल है।
failed — अनुरोध त्रुटिग्रस्त हुआ और त्रुटि विवरण पेलोड में शामिल हैं।

मध्यवर्ती स्थितियाँ (IN_QUEUE, IN_PROGRESS) webhook को ट्रिगर नहीं करतीं। यदि आपको प्रगति अपडेट की भी आवश्यकता है, तो ऊपर वर्णित स्ट्रीमिंग या पोलिंग एंडपॉइंट के साथ webhook का उपयोग करें।

अनुरोध प्रारूप

Sunra आपके webhook URL पर POST अनुरोध भेजता है, जिसमें ये हेडर होते हैं:

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

आपके एंडपॉइंट को 5 सेकंड के भीतर 2xx स्टेटस कोड के साथ प्रतिक्रिया देनी चाहिए। तेज़ी से स्वीकार करें और किसी भी भारी कार्य को बैकग्राउंड जॉब में स्थानांतरित करें — धीमी प्रतिक्रियाओं को विफलता माना जाता है और पुनः प्रयास ट्रिगर करते हैं।

पेलोड

सफल इवेंट:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "स्टूडियो जिबली से प्रेरित एक समुद्री किनारे का शहर..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

विफलता इवेंट output को error से बदल देता है। error की सटीक सामग्री विफलता के प्रकार के अनुसार बदलती है — नीचे दिया गया उदाहरण एक सामान्य रूप दर्शाता है:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "स्टूडियो जिबली से प्रेरित एक समुद्री किनारे का शहर..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "मानव-पठनीय त्रुटि संदेश"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

फ़ील्ड	विवरण
`id`	सबमिट के समय लौटाया गया `request_id`। इसका उपयोग पुनः प्रयासों को डीडुप्लिकेट करने के लिए करें।
`object`	हमेशा `"prediction"`।
`model`	मॉडल का स्वामी और नाम (जैसे `black-forest-labs/flux-1.1-pro`)।
`model_endpoint`	एंडपॉइंट स्लग (जैसे `text-to-image`)।
`status`	`"succeeded"` या `"failed"`।
`input`	आपके द्वारा सबमिट किया गया मूल अनुरोध बॉडी।
`output`	`succeeded` पर मौजूद। परिणाम एंडपॉइंट द्वारा लौटाया गया वही प्रतिक्रिया बॉडी।
`error`	`failed` पर मौजूद। विफलता का वर्णन करने वाला एक ऑब्जेक्ट; इसकी संरचना विफलता के प्रकार पर निर्भर करती है।
`created_at`	अनुरोध बनाए जाने का ISO 8601 टाइमस्टैम्प।
`completed_at`	अनुरोध के अंतिम स्थिति में पहुँचने का ISO 8601 टाइमस्टैम्प।

पुनः प्रयास व्यवहार

Webhook डिलीवरी कम-से-कम-एक-बार होती है। यदि आपका एंडपॉइंट टाइमआउट (5 सेकंड) करता है या गैर-2xx स्टेटस लौटाता है, तो Sunra एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास करता है — 3 पुनः प्रयासों तक 10 सेकंड से शुरू और 30 सेकंड पर सीमित विलंब के साथ। अंतिम पुनः प्रयास के बाद, विफलता को लॉग किया जाता है और कोई और प्रयास नहीं किए जाते। चूँकि पुनः प्रयास एक ही इवेंट को एक से अधिक बार वितरित कर सकते हैं, आपका हैंडलर idempotent होना चाहिए — डीडुप कुंजी के रूप में id फ़ील्ड का उपयोग करें।

सर्वोत्तम अभ्यास

HTTPS का उपयोग करें और सत्यापित करें कि ट्रैफ़िक उस एंडपॉइंट तक पहुंच रहा है जिसकी आप अपेक्षा करते हैं।
तुरंत 2xx के साथ प्रतिक्रिया दें और पेलोड को असिंक्रोनस रूप से प्रोसेस करें।
डिलीवरी को कम-से-कम-एक-बार के रूप में मानें और id के अनुसार डीडुप करें।
यदि आपको अंतिम घटना से पहले प्रगति अपडेट की आवश्यकता है, तो webhook को पोलिंग या स्ट्रीमिंग एंडपॉइंट के साथ संयोजित करें।

अनुरोध रद्द करना

यदि आपका अनुरोध अभी भी कतार में है, तो आप इसे रद्द कर सकते हैं:

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

प्रतिक्रियाएं प्राप्त करना

एक बार जब आपका अनुरोध COMPLETED हो जाए, तो प्रतिक्रिया प्राप्त करें:

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

यह समापन बिंदु समीक्षा के लिए लॉग भी प्रदान करता है।

Sunra क्लाइंट के साथ सरलीकृत एकीकरण

Sunra क्लाइंट स्थिति ट्रैकिंग को स्वचालित करता है, जिससे Sunra कार्यों के साथ ऐप विकास सरल हो जाता है।

दर सीमाएं

उचित उपयोग और सिस्टम स्थिरता सुनिश्चित करने के लिए, हमारे API समापन बिंदु निम्नलिखित दर सीमाओं के अधीन हैं:

समापन बिंदु प्रकार	दर सीमा	बर्स्ट सीमा
कतार में सबमिट करें	10 अनुरोध/सेकंड	100 अनुरोध/मिनट
अन्य सभी समापन बिंदु	100 अनुरोध/सेकंड	1,800 अनुरोध/मिनट

यदि आप इन सीमाओं को पार करते हैं, तो आपको 403 निषिद्ध प्रतिक्रिया प्राप्त होगी। हम इन मामलों को संभालने के लिए घातीय बैकऑफ़ के साथ एक पुनर्प्रयास तंत्र को लागू करने की सलाह देते हैं।

अवलोकन

Multimodal

LLM

क्लाइंट लाइब्रेरी

कतार समापन बिंदु

अनुरोध की स्थिति

समापन बिंदु उपयोग

उदाहरण प्रतिक्रिया

संभावित स्थितियाँ

लॉग सक्षम करना

रीयल-टाइम निगरानी

Webhooks

Webhooks सक्षम करना

Webhook कब फायर होता है

अनुरोध प्रारूप

पेलोड

पुनः प्रयास व्यवहार

सर्वोत्तम अभ्यास

अनुरोध रद्द करना

प्रतिक्रियाएं प्राप्त करना

Sunra क्लाइंट के साथ सरलीकृत एकीकरण

दर सीमाएं

​कतार समापन बिंदु

​अनुरोध की स्थिति

​समापन बिंदु उपयोग

​उदाहरण प्रतिक्रिया

​संभावित स्थितियाँ

​लॉग सक्षम करना

​रीयल-टाइम निगरानी

​Webhooks

​Webhooks सक्षम करना

​Webhook कब फायर होता है

​अनुरोध प्रारूप

​पेलोड

​पुनः प्रयास व्यवहार

​सर्वोत्तम अभ्यास

​अनुरोध रद्द करना

​प्रतिक्रियाएं प्राप्त करना

​Sunra क्लाइंट के साथ सरलीकृत एकीकरण

​दर सीमाएं

कतार समापन बिंदु

अनुरोध की स्थिति

समापन बिंदु उपयोग

उदाहरण प्रतिक्रिया

संभावित स्थितियाँ

लॉग सक्षम करना

रीयल-टाइम निगरानी

Webhooks

Webhooks सक्षम करना

Webhook कब फायर होता है

अनुरोध प्रारूप

पेलोड

पुनः प्रयास व्यवहार

सर्वोत्तम अभ्यास

अनुरोध रद्द करना

प्रतिक्रियाएं प्राप्त करना

Sunra क्लाइंट के साथ सरलीकृत एकीकरण

दर सीमाएं