مهارة الوكيل

# مهارة DeepManim API

يمكنك استخدام DeepManim API لتوليد فيديوهات شرح متحركة وتحسينها وإضافة تعليق صوتي إليها انطلاقًا من طلبات نصية.

## عنوان URL الأساسي

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

## المصادقة

تتطلب جميع الطلبات مفتاح API في ترويسة Authorization:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## سير العمل

سير العمل المعتاد هو:

1. **ولّد** فيديو من طلب نصي عبر `POST /generate`
2. **استعلم** عن المهمة المُعادة عبر `GET /jobs/{job_id}` حتى تصبح `status` مساوية لـ `"completed"`
3. **حسّن** الفيديو بتعليمات متابعة عبر `POST /improve` (اختياري وقابل للتكرار)
4. **أضف** تعليقًا صوتيًا عبر `POST /audio` بعد رضاك عن العناصر البصرية
5. **حسّن التعليق الصوتي** عبر `POST /improve-narration` عند الحاجة

تبدأ طلبات التوليد والتحسين من 1.5 رصيد وتختلف حسب الإعداد المسبق. تكلف طلبات الصوت وتحسين التعليق الصوتي رصيدًا واحدًا. قراءة البيانات مجانية.

## نقاط النهاية

### POST /generate
ولّد فيديو جديدًا من طلب نصي. يُضمّن التعليق الصوتي افتراضيًا.

جسم الطلب:
```json
{
  "message": "اشرح الجاذبية",
  "session_id": null,
  "preferred_locale": "ar"
}
```
- `message` (required): الطلب الذي يصف ما يجب تحريكه.
- `session_id` (optional): مرّر معرّف جلسة موجودًا لمتابعة محادثة.

الاستجابة:
```json
{
  "job_id": "abc-123",
  "session_id": "def-456",
  "status": "pending"
}
```

### POST /improve
حسّن فيديو موجودًا أو عدّله. لا يتضمن الصوت — أضفه منفصلًا عبر /audio بعد جميع التعديلات.

جسم الطلب:
```json
{
  "session_id": "def-456",
  "message": "أضف ألوانًا أكثر وأبطئ الحركة",
  "preferred_locale": "ar"
}
```

الاستجابة:
```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": "ar"
}
```

### POST /improve-narration
حسّن التعليق الصوتي الموجود في فيديو.

جسم الطلب:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "اجعل الشرح أكثر بداهة للمبتدئين.",
  "preferred_locale": "ar"
}
```

### 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} — احصل على رسالة واحدة باستخدام معرّفها.

### 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": "ar"
})
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": "ar"
})
# استعلم عن 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": "ar"
})
# استعلم عن 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": "ar"
})
# استعلم عن job_id الجديد…
```