> ## 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        | डालना | एक अनुरोध रद्द करता है                   |

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

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

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

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

पेलोड में `request_id` शामिल है और स्थिति की जाँच, रद्द करने या प्रतिक्रिया प्राप्त करने के लिए URL प्रदान करता है, जिससे अतिरिक्त समापन बिंदु विकास के बिना आपके वर्कफ़्लो को सुव्यवस्थित किया जा सके।

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

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

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

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status
```

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

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

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

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

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

* **IN\_QUEUE**: इंगित करता है कि अनुरोध संसाधित होने की प्रतीक्षा कर रहा है।
  * `queue_position`: कतार में आपका स्थान दिखाता है।
  * `response_url`: प्रसंस्करण पूरा होने पर प्रतिक्रिया प्राप्त करने के लिए URL।

* **IN\_PROGRESS**: अनुरोध वर्तमान में संसाधित किया जा रहा है।
  * `logs`: प्रसंस्करण चरणों को दर्शाने वाले विस्तृत लॉग (यदि सक्षम हो)।
  * `response_url`: जहां अंतिम प्रतिक्रिया उपलब्ध होगी।

* **COMPLETED**: प्रसंस्करण समाप्त हो गया है।
  * `logs`: पूरी प्रक्रिया का विवरण देने वाले लॉग।
  * `response_url`: आपकी पूरी की गई प्रतिक्रिया का सीधा लिंक।

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

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

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

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

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

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

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

```bash theme={null}
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` क्वेरी पैरामीटर जोड़ें:

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

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` स्टेटस कोड के साथ प्रतिक्रिया देनी चाहिए। तेज़ी से स्वीकार करें और किसी भी भारी कार्य को बैकग्राउंड जॉब में स्थानांतरित करें — धीमी प्रतिक्रियाओं को विफलता माना जाता है और पुनः प्रयास ट्रिगर करते हैं।

### पेलोड

सफल इवेंट:

```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": "स्टूडियो जिबली से प्रेरित एक समुद्री किनारे का शहर..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}
```

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

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

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

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

```bash theme={null}
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel
```

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

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

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
```

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

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

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

## दर सीमाएं

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

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

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