# प्रमाणीकरण

हर वह कॉल जो किसी मॉडल को चलाती है या आपके अनुरोध पढ़ती है, उसके लिए API कुंजी आवश्यक है। कैटलॉग (`GET /models`,
`GET /categories`), `POST /quote` और OpenAPI दस्तावेज़ सार्वजनिक हैं।

## API कुंजियाँ

[https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) पर कुंजियाँ बनाएँ और रद्द करें। कुंजी `doitong_` के बाद आने वाले
64 हेक्स वर्णों जैसी दिखती है और इसे बनाने के समय केवल एक बार दिखाया जाता है। इसे
`Authorization` हेडर में भेजें:

```bash
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"
```

`X-API-Key: <key>` भी काम करता है।

> [!WARNING]
> कुंजियों को अपने सर्वर पर रखें: जिसके पास कुंजी है, वह उसके लिए अनुमत API क्रेडिट खर्च कर सकता है। यदि कोई कुंजी लीक हो जाए,
> तो उसे रद्द करके नई कुंजी बनाएँ।

बिना कुंजी वाले अनुरोध कोड `missing_api_key` के साथ `401` प्राप्त करते हैं; अज्ञात, रद्द की गई या समाप्त हो चुकी कुंजी को भी `401` मिलता है।

## स्कोप

हर कुंजी में स्कोप होते हैं। मॉडल API इनकी जाँच करता है:

| कार्रवाई | आवश्यक स्कोप |
|---|---|
| मॉडल चलाना, अनुरोध रद्द करना, अनुरोध की फ़ाइलें हटाना, स्टोरेज सेटिंग बदलना | `models:run` (पुराने `images:create` या `videos:create` वाली कुंजियाँ भी काम करती हैं) |
| अपलोड URL बनाना | `models:run` या `media:upload` |
| अनुरोध और खाता पढ़ना | `models:read` (मॉडल चलाने वाली कुंजी इन्हें भी पढ़ सकती है) |

नई कुंजियों को डिफ़ॉल्ट रूप से `models:read` और `models:run` मिलते हैं। सही स्कोप के बिना कॉल कोड
`insufficient_scope` के साथ `403` प्राप्त करती है।

## क्रेडिट बजट

खाता स्वामी द्वारा API क्रेडिट (1,000 API क्रेडिट = $1) में किसी कुंजी का अपना बजट सेट किया जा सकता है: कुल बजट, दैनिक बजट (पिछले 24 घंटे), या दोनों। किसी रन के लिए शुल्क लेने से पहले, इस API के माध्यम से कुंजी द्वारा पहले ही खर्च की गई राशि (रिफंड घटाने के बाद) के विरुद्ध लागत की जाँच की जाती है। जो रन इस सीमा से अधिक हो जाता, उसे `402 budget_exceeded` के साथ अस्वीकार कर दिया जाता है और कोई शुल्क नहीं लिया जाता।

> [!IMPORTANT]
> बजट अस्वीकृति अंतिम होती है: स्वामी द्वारा बजट बढ़ाए जाने तक दोबारा प्रयास करने से मदद नहीं मिलेगी।

 बिना बजट वाली कुंजी API शेष राशि तक खर्च कर सकती है। अलग से, जिस रन की लागत API शेष राशि से पूरी नहीं हो सकती, उसे `402 insufficient_credits` के साथ `top_up_url` मिलता है।

`GET https://api.doitong.com/v1/account` API शेष राशि और कुंजी का शेष बजट (दोनों API क्रेडिट में) दिखाता है:

```json 200 OK · खाता
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}
```

जब कुंजी का अपना कोई बजट नहीं होता, तब `budget_remaining` का मान `null` होता है।

## रेट सीमाएँ

हर कुंजी प्रति घंटे 3600 अनुरोध कर सकती है, जब तक कि उसकी सीमा अलग तरीके से सेट न की गई हो। हर प्रमाणीकृत प्रतिक्रिया में वर्तमान स्थिति होती है:

| हेडर | अर्थ |
|---|---|
| `X-RateLimit-Limit` | वर्तमान विंडो में अनुमत अनुरोध |
| `X-RateLimit-Remaining` | वर्तमान विंडो में बचे अनुरोध |
| `X-RateLimit-Reset` | विंडो रीसेट होने का Unix समय |

सीमा पार करने पर आपको `Retry-After` हेडर (सेकंड) के साथ `429` मिलता है। `?wait=` के साथ लंबे पोलिंग में प्रति कॉल एक अनुरोध गिना जाता है, इसलिए तेज़ी से पोलिंग करने की तुलना में प्रतीक्षा करना सस्ता है।

प्रति खाते प्रगति में (`queued` या `running`) 10 अनुरोधों की एक सीमा भी है। एक और शुरू करने पर `429 too_many_inflight` मिलता है; किसी एक के पूरा होने के बाद इसे फिर शुरू करें।