मुख्य सामग्री पर जाएं

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 अनुप्रयोगों में आम तौर पर कुछ सेकंड से अधिक समय लेने वाले अनुरोधों के लिए, हमने एक कतार प्रणाली विकसित की है। यह प्रणाली आपको ट्रैफिक उछाल को प्रबंधित करने, जरूरत पड़ने पर अनुरोध रद्द करने और कतार में अपने अनुरोध की स्थिति की निगरानी करने के लिए सूक्ष्म नियंत्रण प्रदान करती है। यह लंबे समय तक चलने वाले 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 अनुरोध भेजता है, जिसमें ये हेडर होते हैं:
HeaderValue
Content-Typeapplication/json
User-AgentSunra-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आपके द्वारा सबमिट किया गया मूल अनुरोध बॉडी।
outputsucceeded पर मौजूद। परिणाम एंडपॉइंट द्वारा लौटाया गया वही प्रतिक्रिया बॉडी।
errorfailed पर मौजूद। विफलता का वर्णन करने वाला एक ऑब्जेक्ट; इसकी संरचना विफलता के प्रकार पर निर्भर करती है।
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 निषिद्ध प्रतिक्रिया प्राप्त होगी। हम इन मामलों को संभालने के लिए घातीय बैकऑफ़ के साथ एक पुनर्प्रयास तंत्र को लागू करने की सलाह देते हैं।