# فوری آغاز

چند منٹ میں اپنی پہلی تخلیق چلائیں۔ تمام 1,496 ماڈل ایک ہی قسم کی درخواست لیتے ہیں اور تصویر، ویڈیو اور آڈیو کے لیے ایک ہی درخواست آبجیکٹ واپس کرتے ہیں: اسے یہاں ایک بار سیکھیں۔

> [!NOTE]
> بنیادی URL `https://api.doitong.com/v1` ہے۔ ہر کال `Authorization: Bearer <your key>` بھیجتی ہے، اور یہی کلید HTTP
> API اور MCP سرور دونوں کے لیے کام کرتی ہے۔

## 1. API کلید حاصل کریں

[https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) پر کلید بنائیں اور اسے ایک ماحولیاتی
متغیر میں رکھیں: یہ صرف ایک بار دکھائی جاتی ہے۔ ہر کلید کا اپنا بجٹ ہو سکتا ہے، اس لیے آپ پورے اکاؤنٹ کو خطرے
میں ڈالے بغیر ایک کلید ایجنٹ کو دے سکتے ہیں۔ `GET /account` آپ کا API بیلنس واپس کرتا ہے۔

```bash
export DOITONG_API_KEY="doitong_..."

curl "https://api.doitong.com/v1/account" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const res = await fetch("https://api.doitong.com/v1/account", {
  headers: { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` },
});

console.log(await res.json());
```
```python
import os
import requests

r = requests.get(
    "https://api.doitong.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"},
)
print(r.json())
```

چلنے والی درخواستوں کی ادائیگی آپ کے اکاؤنٹ کے **API بیلنس** سے API کریڈٹس میں ہوتی ہے: 1,000 API کریڈٹس = ⁨$1⁩، اور ہر ماڈل
کی قیمت اس کے بنانے والے کی مقررہ قیمت کے عین مطابق ہوتی ہے۔ [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) پر ٹاپ اَپ کریں۔

## 2. قیمت معلوم کریں، پھر چلائیں

`POST /quote/{model_id}` ان پٹ JSON لیتا ہے اور عین قیمت واپس کرتا ہے۔ اسے کلید کی ضرورت نہیں اور اس کی کوئی قیمت نہیں۔
اسی ان پٹ کو چلانے کی لاگت بھی یہی ہوتی ہے: کوٹ ہی چارج ہے۔ (استعمال کے حساب سے چارج ہونے والا ماڈل مستثنیٰ ہے:
اس کا کوٹ زیادہ سے زیادہ ممکنہ لاگت ہوتا ہے، اور غیر استعمال شدہ حصہ چلنے کے بعد واپس کر دیا جاتا ہے۔)

```bash
curl -X POST "https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": true}'
```
```javascript
const res = await fetch("https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ image: "https://example.com/fox.jpg", duration: 5, generate_audio: true }),
});

const quote = await res.json();
console.log(quote.credits, quote.usd); // 840 "0.84"
```
```python
import requests

r = requests.post(
    "https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video",
    json={"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": True},
)
print(r.json()["credits"], r.json()["usd"])  # 840 0.84
```

```json 200 OK · کوٹ
{
  "object": "quote",
  "model": "kling-video/v3/pro/image-to-video",
  "credits": 840,
  "usd": "0.84",
  "unit": "second",
  "quantity": 5,
  "unit_credits": 168,
  "mode": "exact",
  "breakdown": "5 s × 168 API credits"
}
```

پھر یہی باڈی `POST /run/{model_id}` کو بھیجیں۔ کنکشن کو زیادہ سے زیادہ 20 سیکنڈ روکنے کے لیے `?wait=20` شامل کریں:
تیز ماڈل ایک ہی راؤنڈ ٹرپ میں مکمل نتیجہ واپس کرتا ہے۔ `Idempotency-Key` ہیڈر بھیجیں تاکہ دوبارہ کوشش کرنے پر درخواست
دوبارہ نہ چلے (اور دوبارہ چارج نہ ہو)۔

```bash
curl -X POST "https://api.doitong.com/v1/run/flux/schnell?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lighthouse-001" \
  -d '{"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"}'
```
```javascript
const res = await fetch("https://api.doitong.com/v1/run/flux/schnell?wait=20", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DOITONG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "lighthouse-001",
  },
  body: JSON.stringify({ prompt: "A lighthouse on a rocky coast at dusk, warm light in the window" }),
});

const request = await res.json();
console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

r = requests.post(
    "https://api.doitong.com/v1/run/flux/schnell",
    params={"wait": 20},
    headers={
        "Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}",
        "Idempotency-Key": "lighthouse-001",
    },
    json={"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"},
)
request = r.json()
print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

جواب ایک درخواست آبجیکٹ ہوتا ہے:

```json 200 OK · درخواست
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg", "width": 1024, "height": 768, "stored": true }
  ],
  "error": null
}
```

## 3. اسٹیٹس دیکھیں

اگر انتظار ختم ہونے پر ماڈل ابھی کام کر رہا ہو تو آپ کو درخواست کی `id` اور موجودہ `status` کے ساتھ `202 Accepted` ملتا ہے۔
ہر درخواست ایک ہی لائف سائیکل سے گزرتی ہے:

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

اس کی id کے ذریعے درخواست دوبارہ پڑھیں۔ یہاں بھی `?wait=20` کام کرتا ہے، اس لیے ایک سادہ لوپ کافی ہے:

```bash
curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const headers = { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` };
let request = await (await fetch("https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20", { headers })).json();

while (request.status === "queued" || request.status === "running") {
  const res = await fetch(`https://api.doitong.com/v1/requests/${request.id}?wait=20`, { headers });
  request = await res.json();
}

console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

headers = {"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"}
request = {"id": "req_8k2m4q7x1z9c3v5b6n0p2r4t", "status": "queued"}

while request["status"] in ("queued", "running"):
    request = requests.get(
        f"https://api.doitong.com/v1/requests/{request['id']}",
        params={"wait": 20},
        headers=headers,
    ).json()

print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

جب `status`، `succeeded` ہو تو `outputs[].url` ہمارے اسٹوریج میں موجود فائلوں کے لنکس رکھتا ہے۔ اگر درخواست `failed` یا
`canceled` ہو جائے تو اس کے API کریڈٹس خودکار طور پر واپس کر دیے جاتے ہیں اور `error` وجہ بتاتا ہے۔ جو کچھ ابھی `queued`
یا `running` ہو اسے منسوخ کریں:

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

طویل ویڈیو جابز کے لیے پولنگ چھوڑ کر اس کے بجائے `webhook_url` پاس کر سکتے ہیں ([Webhooks](https://doitong.com/developers/docs/webhooks) دیکھیں)۔

## 4. فائلیں

کسی بھی عوامی URL کو ان پٹ کے طور پر پاس کریں، یا اپ لوڈ URL کے لیے `POST /files` سے درخواست کریں، وہاں فائل کو `PUT` کریں
اور واپس ملنے والا `file_url` استعمال کریں ([Files](https://doitong.com/developers/docs/files) دیکھیں)۔ کامیاب درخواست اپنے نتائج
`outputs[]` میں درج کرتی ہے، جن کے ساتھ type، content type اور، جب معلوم ہو، dimensions اور duration شامل ہوتے ہیں۔

```bash
curl -X POST "https://api.doitong.com/v1/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "fox.jpg", "content_type": "image/jpeg", "size": 482113}'
```

> [!TIP]
> **فائلیں ہمیشہ کے لیے محفوظ رکھیں، یا 7 دن مفت: انتخاب آپ کا ہے۔** درخواست کامیاب ہونے سے پہلے
> آؤٹ پٹ فائلیں ہمارے اسٹوریج میں کاپی کی جاتی ہیں۔ ڈیفالٹ طور پر وہ آپ کے حذف کرنے تک رہتی ہیں (100 API کریڈٹس
> فی GB فی ماہ)؛ ڈیش بورڈ میں "فائلیں ہمیشہ کے لیے محفوظ رکھیں" بند کریں، یا `?storage=temporary` پاس کریں، تاکہ وہ 7
> دن مفت رہیں ([Files](https://doitong.com/developers/docs/files#storage) دیکھیں)۔

## خرابیاں

ہر ماڈل ایک ہی طرح ناکام ہوتا ہے: ایک envelope میں `type`، عین `code`، مسئلہ پیدا کرنے والا `param` اور `details` میں ہر مسئلہ
ہوتا ہے، تاکہ ایجنٹ نثر پڑھے بغیر درخواست درست کر سکے۔ غیر درست درخواست پر کوئی چارج نہیں ہوتا۔

```json 422 Unprocessable Entity
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

ہر type اور code [Errors](https://doitong.com/developers/docs/errors) میں درج ہے۔

## قیمتیں

قیمتیں USD اور API کریڈٹس میں ہوتی ہیں اور چلانے سے پہلے ہر ماڈل کے صفحے پر دکھائی جاتی ہیں۔ ہر درخواست میں `cost` کے ساتھ
`credits`، `usd`، `charged` اور `refunded` شامل ہوتے ہیں۔ درخواست قبول ہونے پر چارج ہوتی ہے؛ `failed` اور `canceled` درخواستوں
کی رقم خودکار طور پر واپس کی جاتی ہے۔ کچھ ماڈلز کی قیمت ان پٹ سے عین طے ہوتی ہے، کچھ آپ کی بھیجی ہوئی فائلوں کی لمبائی یا حجم
کے مطابق، جبکہ دیگر *ہر رن کی تخمینی قیمت* لیتے ہیں: ہر صورت میں کوٹ ہی آپ کی ادائیگی ہے۔ چند ماڈلز (زبان اور وژن ماڈلز، آواز
اور پروسیسنگ وقت کے ٹولز) *استعمال کے حساب سے چارج* ہوتے ہیں: کوٹ زیادہ سے زیادہ ممکنہ قیمت ہے، اور رن میں استعمال نہ ہونے والا
حصہ خودکار طور پر واپس کر دیا جاتا ہے۔ [Pricing](https://doitong.com/developers/docs/pricing) دیکھیں۔

## MCP اور AI ایجنٹس

اسی Bearer کلید کے ساتھ کسی بھی MCP کلائنٹ کو `https://api.doitong.com/v1/mcp` سے جوڑیں۔ آپ کا ایجنٹ کیٹلاگ تلاش، ماڈلز کا کوٹ اور رن،
اور ہر دستاویزاتی صفحہ Markdown کے طور پر پڑھ سکتا ہے۔

```bash Claude Code
claude mcp add --transport http doitong-models https://api.doitong.com/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## اگلے مراحل

- [تمام ماڈلز](https://doitong.com/developers/models) دیکھیں۔ ہر صفحے پر درخواست بنانے والا ٹول موجود ہے جو آپ کے لیے کوڈ لکھتا ہے۔
- درخواست کا لائف سائیکل سیکھیں: [Requests](https://doitong.com/developers/docs/requests)۔
- ہر ماڈل پر پیرامیٹر کے وہی نام استعمال کریں: [Parameters](https://doitong.com/developers/docs/parameters)۔
- AI کوڈنگ ایجنٹ کے ساتھ کام کر رہے ہیں؟ اسے [https://doitong.com/developers/llms.txt](https://doitong.com/developers/llms.txt) دیں یا [MCP server](https://doitong.com/developers/docs/mcp) سے جوڑیں۔