ایجنٹ مہارت

# DeepManim API مہارت

آپ DeepManim API سے ٹیکسٹ پرامپٹس کے ذریعے متحرک تعلیمی ویڈیوز بنا، بہتر اور وائس اوور کے ساتھ تیار کر سکتے ہیں۔

## بنیادی URL

```
https://api.deepmanim.com/api/v1
```

## تصدیق

تمام درخواستوں کے Authorization ہیڈر میں API کی درکار ہے:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## ورک فلو

عام ورک فلو یہ ہے:

1. ٹیکسٹ پرامپٹ سے `POST /generate` کے ذریعے ویڈیو **بنائیں**
2. `GET /jobs/{job_id}` سے جاب مکمل ہونے تک **حالت چیک کریں**
3. `POST /improve` کے ذریعے فالو اَپ ہدایات سے ویڈیو **بہتر بنائیں** (اختیاری، بار بار ممکن)
4. بصری نتیجے سے مطمئن ہونے پر `POST /audio` کے ذریعے وائس اوور **شامل کریں**
5. ضرورت ہو تو `POST /improve-narration` کے ذریعے **وائس اوور بہتر کریں**

تخلیق اور بہتری کی کالز 1.5 کریڈٹس سے شروع ہوتی ہیں اور پری سیٹ کے مطابق بدلتی ہیں۔ آڈیو اور improve-narration کالز کی قیمت 1 کریڈٹ ہے۔ ڈیٹا پڑھنا مفت ہے۔

## اینڈ پوائنٹس

### POST /generate
ٹیکسٹ پرامپٹ سے نئی ویڈیو بنائیں۔ وائس اوور ڈیفالٹ طور پر شامل ہے۔

درخواست کا باڈی:
```json
{
  "message": "کششِ ثقل سمجھائیں",
  "session_id": null,
  "preferred_locale": "ur"
}
```
- `message` (required): کیا اینیمیٹ کرنا ہے، یہ بیان کرنے والا پرامپٹ۔
- `session_id` (optional): گفتگو جاری رکھنے کے لیے موجودہ سیشن ID دیں۔

جواب:
```json
{
  "job_id": "abc-123",
  "session_id": "def-456",
  "status": "pending"
}
```

### POST /improve
موجودہ ویڈیو بہتر یا تبدیل کریں۔ آڈیو شامل نہیں؛ تمام تبدیلیوں کے بعد /audio کے ذریعے شامل کریں۔

درخواست کا باڈی:
```json
{
  "session_id": "def-456",
  "message": "مزید رنگ شامل کریں اور اینیمیشن آہستہ کریں",
  "preferred_locale": "ur"
}
```

جواب:
```json
{
  "job_id": "ghi-789",
  "session_id": "def-456",
  "status": "pending"
}
```

### POST /audio
موجودہ ویڈیو میں وائس اوور آڈیو شامل کریں۔

درخواست کا باڈی:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "ur"
}
```

### POST /improve-narration
ویڈیو کے موجودہ وائس اوور کو بہتر کریں۔

درخواست کا باڈی:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "وضاحت کو مبتدیوں کے لیے زیادہ بدیہی بنائیں۔",
  "preferred_locale": "ur"
}
```

### GET /jobs/{job_id}
جاب کی حالت دیکھیں۔ `phase` فیلڈ پیش رفت بتاتا ہے: `brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

مکمل ہونے پر جواب:

مکمل جواب:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "کششِ ثقل سمجھائیں",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "وضاحت کو مبتدیوں کے لیے زیادہ بدیہی بنائیں۔"
  }
}
```

`status` کی ممکنہ قدریں: `pending`، `running`، `completed`، `failed`۔

### POST /jobs/{job_id}/cancel — چلتے یا زیرِ انتظار جاب کو منسوخ کریں۔

### GET /sessions — اپنے تمام سیشنز کی فہرست حاصل کریں۔

### GET /sessions/{session_id} — پیغامات کی مکمل تاریخ کے ساتھ سیشن حاصل کریں۔

### DELETE /sessions/{session_id} — سیشن اور اس کے تمام پیغامات حذف کریں۔

### GET /sessions/{session_id}/jobs
سیشن کے جابز کی فہرست۔ اختیاری کوئری پیرامیٹر: `?status=completed`

### GET /messages/{message_id} — ID کے ذریعے ایک پیغام حاصل کریں۔

### GET /credits
بیلنس حاصل کریں: `balance`، `total_used`، `total_purchased`، `plan`۔

### GET /me
صارف کی معلومات حاصل کریں: `id`، `email`، `display_name`۔

## خرابی کے کوڈز

- `401` — API کی غائب یا غیر درست
- `402` — ناکافی کریڈٹس
- `404` — وسیلہ نہیں ملا
- `400` — غیر درست درخواست

## پولنگ کی حکمتِ عملی

جاب عموماً 60–120 سیکنڈ لیتے ہیں۔ `GET /jobs/{job_id}` کو ہر 3–5 سیکنڈ بعد چیک کریں۔ رفتار بدلنے کے لیے `estimated_time_remaining_seconds` استعمال کریں۔ `status` کے `completed` یا `failed` ہونے پر رک جائیں۔

## مثال: مکمل ورک فلو

```python
import requests, time

API_KEY = "dm_k_YOUR_KEY"
BASE = "https://api.deepmanim.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. بنائیں
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "کششِ ثقل سمجھائیں",
    "preferred_locale": "ur"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

# 2. مکمل ہونے تک چیک کریں
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=headers).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(4)

# 3. نتیجہ حاصل کریں
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. اختیاری بہتری
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "مزید رنگ شامل کریں اور اینیمیشن آہستہ کریں",
    "preferred_locale": "ur"
})
# نئے job_id کی بھی اسی طرح پولنگ کریں…

# 5. بہتری کے بعد آڈیو شامل کریں
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "ur"
})
# نئے job_id کی پولنگ کریں…

# 6. وائس اوور کی تدریسی کیفیت اختیاری طور پر بہتر کریں
r = requests.post(f"{BASE}/improve-narration", headers=headers, json={
  "session_id": session_id,
  "message_id": message_id,
  "high_quality": True,
  "mode": "better_narration",
  "instruction": "وضاحت کو مبتدیوں کے لیے زیادہ بدیہی بنائیں۔",
  "preferred_locale": "ur"
})
# نئے job_id کی پولنگ کریں…
```