# توثیق

ماڈل چلانے یا اپنی درخواستیں پڑھنے والی ہر کال کے لیے 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 بیلنس پوری نہ کر سکے اسے `top_up_url` کے ساتھ `402 insufficient_credits` ملتا ہے۔

`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` ملتا ہے؛ ایک کے مکمل ہونے کے بعد اسے دوبارہ شروع کریں۔