# درخواستیں

ایک درخواست ایک ماڈل کی ایک کال ہوتی ہے۔ اس میں ایک 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"
```

| Query پیرامیٹر | مطلب |
|---|---|
| `q` | وہ الفاظ جو نام، id، بنانے والے یا ٹیگز میں سبھی موجود ہونے چاہییں، مثلاً `kling 3`۔ |
| `category` | ایک 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` آبجیکٹ ہوتا ہے ([قیمتیں](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 بھیجتا ہے ([ویب ہُکس](https://doitong.com/developers/docs/webhooks) دیکھیں)۔
- `?storage=permanent` یا `?storage=temporary` منتخب کرتا ہے کہ آؤٹ پٹ فائلیں کتنی دیر رکھی جائیں؛ اس کے بغیر اکاؤنٹ کی ترتیب لاگو ہوتی ہے ([فائلیں کہاں رہتی ہیں](#storage) دیکھیں)۔

درخواست کے کام جاری ہونے کے دوران جواب `202 Accepted` ہوتا ہے، اور انتظار کے دوران مکمل ہونے پر (یا ری پلے ہونے پر، نیچے دیکھیں) `200 OK` ہوتا ہے۔ `Location` اور `Doitong-Request-Id` ہیڈرز درخواست کا URL اور id رکھتے ہیں۔

## اسٹیٹس

درخواست کا لائف سائیکل: `queued` → `running` → `succeeded` | `failed` | `canceled` (حتمی؛ ناکام اور منسوخ شدہ درخواستوں کے API کریڈٹس واپس کر دیے جاتے ہیں).

| Status | مطلب | Final |
|---|---|---|
| `queued` | قبول اور چارج ہو چکی، ورکر کا انتظار ہے۔ `queue_position` قطار میں مقام دکھا سکتا ہے۔ | no |
| `running` | ماڈل تیار کر رہا ہے۔ | no |
| `succeeded` | مکمل۔ `outputs` فائلوں کی فہرست دیتا ہے۔ | yes |
| `failed` | ماڈل یا کسی حد نے اسے روک دیا۔ `error` وجہ بتاتا ہے۔ API کریڈٹس واپس کر دیے جاتے ہیں۔ | yes |
| `canceled` | نتیجہ تیار ہونے سے پہلے منسوخ کی گئی۔ API کریڈٹس واپس کر دیے جاتے ہیں۔ | yes |

وقت کی حد سے زیادہ دیر چلنے والی درخواست `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` میں ہوتا ہے ([استعمال کے مطابق چارج](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):

- وہی کلید اور پہلے جیسی باڈی: اصل درخواست واپس ملتی ہے (`200`، ہیڈر `Idempotent-Replayed: true`) اور دوبارہ کوئی چارج نہیں ہوتا۔
- وہی کلید اور باڈی، ایسے رن کے بعد جو ماڈل تک پہنچنے سے پہلے ناکام ہو گیا ہو (`upstream_error` یا submit پر `internal_error`، `insufficient_credits`، `budget_exceeded`، `too_many_inflight`): کچھ تیار نہیں ہوا اور کوئی چارج نہیں ہوا، اس لیے ناکامی واپس کرنے کے بجائے دوبارہ کوشش ماڈل کو پھر چلاتی ہے۔
- مختلف باڈی کے ساتھ وہی کلید: `409 idempotency_mismatch`۔
- کلیدیں انہیں بھیجنے والی API کلید کے دائرہ کار تک محدود ہیں۔

## فائلیں کہاں رہتی ہیں

ہر آؤٹ پٹ فائل درخواست کو `succeeded` قرار دینے سے پہلے ہمارے اسٹوریج میں کاپی کی جاتی ہے، اس لیے `outputs` میں موجود URLs ہمارے اپنے ہوسٹس پر ہوتے ہیں اور آپ انہیں براہِ راست لنک کر سکتے ہیں۔ وہ کتنی دیر رہیں، یہ آپ کی مرضی ہے:

| Mode | مدت | قیمت |
|---|---|---|
| `permanent` (ڈیفالٹ) | جب تک آپ انہیں حذف نہ کریں | 100 API کریڈٹس (⁨$0.10⁩) فی GB فی ماہ، 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` کے تحت دکھاتا ہے، ساتھ ہی محفوظ کردہ بائٹس اور ماہانہ تخمینے کے۔
- رن پر `?storage=permanent|temporary` (MCP `run` ٹول کا `storage` آرگیومنٹ) اس رن کے لیے اسے اوور رائڈ کرتا ہے۔
- ترتیب تبدیل کرنے سے پہلے سے موجود فائلوں پر کوئی اثر نہیں پڑتا؛ انہیں [`DELETE /requests/{id}/files`](#delete-files) سے حذف کریں۔
- جب API بیلنس اسٹوریج کی ادائیگی نہ کر سکے تو کوئی چارج نہیں ہوتا اور آپ کو ای میل ملتی ہے: 30 دن کے اندر ٹاپ اَپ کریں، ورنہ رکھی گئی فائلیں عارضی ہو جائیں گی اور 7 دن بعد حذف کر دی جائیں گی۔

ہمارے کاپی بنانے میں نایاب صورت میں ناکامی ہو تو اندراج میں `"stored": false` ہوتا ہے اور URL اصل، مختصر مدت والا ہوتا ہے: اسے جلد ڈاؤن لوڈ کریں۔