# अनुरोध

एक अनुरोध किसी एक मॉडल का एक कॉल होता है। इसमें एक id (`req_…`), एक स्थिति, API क्रेडिट में इसकी लागत (1000 = 1 USD), और सफल होने पर जनरेट की गई फ़ाइलें होती हैं। नीचे दिए गए हर एंडपॉइंट से, हर मॉडल के लिए यही ऑब्जेक्ट वापस आता है।

## मॉडल ढूँढें

सभी 1,496 मॉडल का कैटलॉग सार्वजनिक JSON है (कुंजी की आवश्यकता नहीं):

```bash
curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"
```

| क्वेरी पैरामीटर | अर्थ |
|---|---|
| `q` | नाम, id, निर्माता या टैग में मौजूद होने वाले सभी शब्द, जैसे `kling 3`। |
| `category` | एक श्रेणी id, जैसे `text-to-video` या `upscale`। `GET https://api.doitong.com/v1/categories` सभी 21 श्रेणियों को उनकी संख्या के साथ सूचीबद्ध करता है। |
| `lab` | मॉडल का निर्माता, नाम या id से, जैसे `Google` या `black-forest-labs`। |
| `family` | पिछली पंक्ति से मिला `family` id: एक मॉडल के हर वैरिएंट (pro, fast, image-to-video, …)। |
| `mode` | `exact` (कीमत इनपुट से निर्धारित होती है), `measured` (इनपुट फ़ाइलों की लंबाई या आकार से), `estimate` (प्रति रन अनुमानित कीमत) या `metered` (वास्तविक उपयोग के अनुसार शुल्क, प्रति रन अधिकतम सीमा तक)। |
| `limit`, `cursor` | पेज का आकार (1 से 100, डिफ़ॉल्ट 50) और पिछले पेज का `next_cursor`। |

हर पंक्ति में `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` और एक `price` ऑब्जेक्ट होता है ([Pricing](https://doitong.com/developers/docs/pricing#price-objects) देखें)। `GET https://api.doitong.com/v1/models/{model_id}` पूरा इनपुट और आउटपुट JSON Schema, मानक पैरामीटर नाम, कीमत के नियम और एक उदाहरण इनपुट जोड़ता है। अज्ञात `category` या `mode` के लिए `400 invalid_parameter` मिलता है।

## मॉडल चलाएँ

```bash
curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'
```

- बॉडी मॉडल का इनपुट, यानी एक JSON ऑब्जेक्ट, होती है। हर मॉडल पेज इसके पैरामीटर सूचीबद्ध करता है।
- किसी भी शुल्क से पहले इनपुट की जाँच की जाती है। अमान्य इनपुट पर गलत `param` के साथ `422 invalid_input` मिलता है और कोई शुल्क नहीं लगता।
- `?wait=N` (अधिकतम 20 सेकंड) कॉल को तब तक रोकता है, जब तक अनुरोध पूरा न हो जाए या समय समाप्त न हो जाए।
- `?webhook_url=https://…` अनुरोध पूरा होने पर उस URL पर हस्ताक्षरित POST भेजता है ([Webhooks](https://doitong.com/developers/docs/webhooks) देखें)।
- `?storage=permanent` या `?storage=temporary` तय करता है कि आउटपुट फ़ाइलें कितने समय तक रखी जाएँ; इसके बिना खाते की सेटिंग लागू होती है ([Where फ़ाइलें live](#storage) देखें)।

अनुरोध के काम करने के दौरान प्रतिक्रिया `202 Accepted` होती है और प्रतीक्षा के दौरान पूरा होने पर (या रीप्ले होने पर, नीचे देखें) `200 OK` होती है। `Location` और `Doitong-Request-Id` हेडर अनुरोध का URL और id देते हैं।

## स्थितियाँ

अनुरोध का जीवनचक्र: `queued` → `running` → `succeeded` | `failed` | `canceled` (अंतिम; विफल और रद्द किए गए अनुरोधों के API क्रेडिट वापस कर दिए जाते हैं).

| स्थिति | अर्थ | अंतिम |
|---|---|---|
| `queued` | स्वीकार किया गया और शुल्क लिया गया, वर्कर की प्रतीक्षा में। `queue_position` कतार में स्थान दिखा सकता है। | नहीं |
| `running` | मॉडल जनरेट कर रहा है। | नहीं |
| `succeeded` | पूरा हुआ। `outputs` फ़ाइलों की सूची देता है। | हाँ |
| `failed` | मॉडल या किसी सीमा ने इसे रोक दिया। `error` कारण बताता है। API क्रेडिट रिफंड किए जाते हैं। | हाँ |
| `canceled` | परिणाम तैयार होने से पहले रद्द किया गया। API क्रेडिट रिफंड किए जाते हैं। | हाँ |

समय सीमा से अधिक चलने वाला अनुरोध `timeout` कोड के साथ विफल होता है और उसका रिफंड किया जाता है: इमेज के लिए 15 मिनट, वीडियो के लिए 60 मिनट, ऑडियो और बाकी सभी के लिए 30 मिनट।

## अनुरोध ऑब्जेक्ट

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

- `outputs` हर मॉडल के लिए समान होता है: हर जनरेट की गई फ़ाइल के लिए एक एंट्री, जिसमें `type` (`image`, `video`, `audio`, `file` या `3d`), हमारे स्टोरेज का एक `url`, `content_type` और ज्ञात होने पर `file_size`, `width`, `height`, `duration` होते हैं।
- `output` मॉडल का अपना परिणाम ऑब्जेक्ट होता है (इसके फ़ील्ड हर मॉडल पेज पर सूचीबद्ध हैं), जिसमें वही URLs होते हैं।
- `storage` बताता है कि फ़ाइलें कैसे रखी जाती हैं: `mode` (`permanent` या `temporary`), संग्रहीत `bytes`, `expires_at` (अस्थायी फ़ाइल हटाए जाने का समय, स्थायी फ़ाइलों के लिए `null`) और `expired` (फ़ाइलें हट जाने के बाद `true`)।
- `cost.credits` API क्रेडिट में कॉल की कीमत (`cost.usd` USD में), `cost.charged` API शेष राशि से डेबिट की गई राशि और `cost.refunded` वापस की गई राशि होती है। `metered` मॉडल के लिए `cost.credits` शुरुआत में रोकी गई अधिकतम राशि (`cost.held`) होती है; रन सफल होने पर `cost.settled` उपयोग की राशि बताता है और अधिकतम राशि का शेष `cost.refunded` में होता है ([Charged by उपयोग](https://doitong.com/developers/docs/pricing#metered) देखें)।
- अनुरोध विफल होने पर `error` `{ "type": …, "code": …, "message": … }` होता है।

## अनुरोध पढ़ें

```bash
curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

- `?wait=N` (अधिकतम 20 सेकंड) लॉन्ग-पोल करता है: कॉल अनुरोध के अंतिम स्थिति में पहुँचते ही लौटता है, या N सेकंड बाद वर्तमान स्थिति के साथ लौटता है। परिणाम की प्रतीक्षा करने का यह सबसे सरल तरीका है।
- `?logs=1` मॉडल की प्रगति की लॉग पंक्तियाँ (अंतिम 50) `logs` के रूप में जोड़ता है।

आप केवल अपने खाते के अनुरोध पढ़ सकते हैं; किसी अन्य id के लिए `404 request_not_found` मिलता है।

## अनुरोधों की सूची बनाएँ

```bash
curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

नवीनतम पहले। `limit` 1 से 100 तक है (डिफ़ॉल्ट 20), `status` और `model` फ़िल्टर करते हैं। प्रतिक्रिया `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }` होती है; अगले पेज के लिए `cursor=<next_cursor>` भेजें।

## अनुरोध रद्द करें

```bash
curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

- मॉडल शुरू होने से पहले रद्द किया गया: स्थिति `canceled` हो जाती है, API क्रेडिट रिफंड किए जाते हैं और आपको `200` मिलता है।
- पहले से जनरेट हो रहा है: रद्द करने का अनुरोध आगे भेजा जाता है और आपको `"cancel_requested": true` के साथ `202` मिलता है। यदि मॉडल फिर भी पूरा हो जाता है, तो अनुरोध सामान्य रूप से सफल होता है और शुल्क लिया जाता है।
- पहले से अंतिम स्थिति में है: `409 not_cancelable` (पहले से `canceled` अनुरोध केवल `200` लौटाता है)।

## अनुरोध की फ़ाइलें हटाएँ

```bash
curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

अनुरोध की आउटपुट फ़ाइलों की हमारी प्रतियाँ तुरंत हटाता है और उनका स्टोरेज शुल्क रोक देता है। प्रतिक्रिया `storage.expired: true` वाले अनुरोध ऑब्जेक्ट की होती है; इसके URLs रिकॉर्ड में बने रहते हैं, लेकिन अब काम नहीं करते। इसे फिर कॉल करने पर कुछ नहीं बदलता (`200`)। `queued` या `running` अनुरोध में अभी कोई फ़ाइल नहीं होती: `409 request_active`। इसके लिए `models:run` आवश्यक है।

## Idempotency: दो बार भुगतान किए बिना पुनः प्रयास

नेटवर्क विफल हो सकते हैं। रन को सुरक्षित रूप से दोबारा आज़माने के लिए `Idempotency-Key` हेडर भेजें (255 वर्णों तक की कोई भी स्ट्रिंग, प्रति ऑपरेशन अद्वितीय, जैसे आपका अपना ऑर्डर id):

- पहले जैसा ही key और body: आपको मूल अनुरोध वापस मिलता है (`200`, हेडर `Idempotent-Replayed: true`) और दोबारा कोई शुल्क नहीं लिया जाता।
- ऐसे रन के बाद वही key और body, जो मॉडल तक पहुँचने से पहले विफल हुआ था (`upstream_error` या `internal_error` on submit, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): कुछ भी जनरेट नहीं हुआ और कोई शुल्क नहीं लिया गया, इसलिए विफलता लौटाने के बजाय पुनः प्रयास मॉडल को फिर चलाता है।
- अलग body के साथ वही key: `409 idempotency_mismatch`।
- Keys उस API कुंजी तक सीमित होती हैं जिसने उन्हें भेजा है।

## फ़ाइलें कहाँ रहती हैं

हर आउटपुट फ़ाइल अनुरोध को `succeeded` चिह्नित करने से पहले हमारे स्टोरेज में कॉपी की जाती है, इसलिए `outputs` में दिए गए URLs हमारे अपने होस्ट पर होते हैं और आप उनसे सीधे लिंक कर सकते हैं। वे कितने समय तक रहेंगी, यह आपकी पसंद है:

| मोड | अवधि | कीमत |
|---|---|---|
| `permanent` (डिफ़ॉल्ट) | जब तक आप उन्हें हटाएँ | प्रति GB प्रति माह 100 API क्रेडिट ($0.10), API शेष राशि से प्रतिदिन शुल्क |
| `temporary` | 7 दिनों तक, फिर हटाई जाती हैं | निःशुल्क |

- खाता सेटिंग नए अनुरोधों के लिए तय करती है: [डैशबोर्ड](https://doitong.com/developers/dashboard#balance) में "फ़ाइलें हमेशा के लिए रखें" स्विच, या `PATCH https://api.doitong.com/v1/account/storage` के साथ `{"mode": "temporary"}`। `GET https://api.doitong.com/v1/account` इसे `storage` के अंतर्गत दिखाता है, साथ में आपके रखे गए bytes और मासिक अनुमान के साथ।
- रन पर `?storage=permanent|temporary` (MCP `run` टूल का `storage` आर्ग्युमेंट) उस रन के लिए इसे ओवरराइड करता है।
- सेटिंग बदलने से आपके पास पहले से मौजूद फ़ाइलों पर कोई प्रभाव नहीं पड़ता; उन्हें [`DELETE /requests/{id}/files`](#delete-files) से हटाएँ।
- जब API शेष राशि स्टोरेज का भुगतान नहीं कर सकती, तो कोई शुल्क नहीं लिया जाता और आपको ईमेल मिलता है: 30 दिनों के भीतर टॉप-अप करें, अन्यथा रखी गई फ़ाइलें अस्थायी हो जाएँगी और 7 दिनों बाद हटा दी जाएँगी।

दुर्लभ स्थिति में जब हमारी कॉपी विफल हो जाती है, तो एंट्री में `"stored": false` होता है और URL मूल, कम समय तक उपलब्ध रहने वाला URL होता है: इसे जल्द डाउनलोड करें।