درخواستیں

ایک درخواست ایک ماڈل کی ایک کال ہوتی ہے۔ اس میں ایک id (req_…)، ایک اسٹیٹس، API کریڈٹس میں اس کی لاگت (1000 = 1 USD)، اور کامیاب ہونے پر تیار کردہ فائلیں شامل ہوتی ہیں۔ نیچے موجود ہر اینڈ پوائنٹ سے، ہر ماڈل کے لیے یہی آبجیکٹ واپس آتا ہے۔

ماڈل تلاش کریں#

تمام 1,496 ماڈلز کا کیٹلاگ عوامی JSON ہے (کلید کی ضرورت نہیں):

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

ہر قطار میں id، name، lab، category، family، summary، tags، output_kind، docs_url اور ایک price آبجیکٹ ہوتا ہے (قیمتیں دیکھیں)۔ GET https://api.doitong.ru/v1/models/{model_id} مکمل ان پٹ اور آؤٹ پٹ JSON Schema، معیاری پیرامیٹر نام، قیمت کے اصول اور مثالی ان پٹ شامل کرتا ہے۔ نامعلوم category یا mode، 400 invalid_parameter ہوتا ہے۔

ماڈل چلائیں#

curl -X POST "https://api.doitong.ru/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 بھیجتا ہے (ویب ہُکس دیکھیں)۔
• ?storage=permanent یا ?storage=temporary منتخب کرتا ہے کہ آؤٹ پٹ فائلیں کتنی دیر رکھی جائیں؛ اس کے بغیر اکاؤنٹ کی ترتیب لاگو ہوتی ہے (فائلیں کہاں رہتی ہیں دیکھیں)۔

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

اسٹیٹس#

وقت کی حد سے زیادہ دیر چلنے والی درخواست timeout کوڈ کے ساتھ ناکام ہوتی ہے اور رقم واپس کر دی جاتی ہے: تصویر کے لیے 15 منٹ، ویڈیو کے لیے 60 منٹ، آڈیو کے لیے 30 منٹ اور باقی سب کے لیے بھی۔

درخواست آبجیکٹ#

{
  "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.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/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 میں ہوتا ہے (استعمال کے مطابق چارج دیکھیں)۔
• درخواست ناکام ہونے پر error { "type": …, "code": …, "message": … } ہوتا ہے۔

درخواست پڑھیں#

curl "https://api.doitong.ru/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 ملتا ہے۔

درخواستوں کی فہرست بنائیں#

curl "https://api.doitong.ru/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> بھیجیں۔

درخواست منسوخ کریں#

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

• ماڈل شروع ہونے سے پہلے منسوخ: اسٹیٹس canceled ہو جاتا ہے، API کریڈٹس واپس کر دیے جاتے ہیں، اور آپ کو 200 ملتا ہے۔
• پہلے ہی تیار ہو رہی ہو: منسوخی آگے بھیج دی جاتی ہے اور آپ کو "cancel_requested": true کے ساتھ 202 ملتا ہے۔ اگر ماڈل پھر بھی مکمل ہو جائے تو درخواست معمول کے مطابق کامیاب ہوتی ہے اور چارج کیا جاتا ہے۔
• پہلے ہی حتمی ہو: 409 not_cancelable (پہلے ہی canceled درخواست صرف 200 واپس کرتی ہے)۔

درخواست کی فائلیں حذف کریں#

curl -X DELETE "https://api.doitong.ru/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 ہمارے اپنے ہوسٹس پر ہوتے ہیں اور آپ انہیں براہِ راست لنک کر سکتے ہیں۔ وہ کتنی دیر رہیں، یہ آپ کی مرضی ہے:

• نئی درخواستوں کے لیے اکاؤنٹ کی ترتیب فیصلہ کرتی ہے: ڈیش بورڈ میں "فائلیں ہمیشہ کے لیے محفوظ رکھیں" سوئچ، یا PATCH https://api.doitong.ru/v1/account/storage کے ساتھ {"mode": "temporary"}۔ GET https://api.doitong.ru/v1/account اسے storage کے تحت دکھاتا ہے، ساتھ ہی محفوظ کردہ بائٹس اور ماہانہ تخمینے کے۔
• رن پر ?storage=permanent|temporary (MCP run ٹول کا storage آرگیومنٹ) اس رن کے لیے اسے اوور رائڈ کرتا ہے۔
• ترتیب تبدیل کرنے سے پہلے سے موجود فائلوں پر کوئی اثر نہیں پڑتا؛ انہیں DELETE /requests/{id}/files سے حذف کریں۔
• جب API بیلنس اسٹوریج کی ادائیگی نہ کر سکے تو کوئی چارج نہیں ہوتا اور آپ کو ای میل ملتی ہے: 30 دن کے اندر ٹاپ اَپ کریں، ورنہ رکھی گئی فائلیں عارضی ہو جائیں گی اور 7 دن بعد حذف کر دی جائیں گی۔

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