مهارت برای عامل‌ها

# مهارت API DeepManim

با API DeepManim می‌توانید از درخواست‌های متنی ویدئوهای توضیحی متحرک تولید، اصلاح و روایت‌گذاری کنید.

## نشانی پایه

```
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`

هزینه فراخوانی‌های تولید و بهبود از ۱٫۵ اعتبار شروع می‌شود و به پیش‌تنظیم وابسته است. فراخوانی‌های صوتی و improve-narration یک اعتبار هزینه دارند. خواندن داده‌ها رایگان است.

## نقاط پایانی

### POST /generate
یک ویدئوی جدید از درخواست متنی تولید می‌کند؛ روایت صوتی به‌صورت پیش‌فرض اضافه می‌شود.

بدنه درخواست:
```json
{
  "message": "گرانش را توضیح دهید",
  "session_id": null,
  "preferred_locale": "fa"
}
```
- `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": "fa"
}
```

پاسخ:
```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": "fa"
}
```

### POST /improve-narration
روایت موجود ویدئو را بهبود می‌دهد.

بدنه درخواست:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "توضیح را برای مبتدیان شهودی‌تر کنید.",
  "preferred_locale": "fa"
}
```

### 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` — درخواست نامعتبر است

## راهبرد بررسی

کارها معمولاً ۶۰ تا ۱۲۰ ثانیه طول می‌کشند. هر ۳ تا ۵ ثانیه `GET /jobs/{job_id}` را بررسی کنید و برای تنظیم فاصله از `estimated_time_remaining_seconds` کمک بگیرید. وقتی وضعیت `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}"}

# ۱. تولید
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "گرانش را توضیح دهید",
    "preferred_locale": "fa"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

# ۲. بررسی تا پایان
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=headers).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(4)

# ۳. دریافت نتیجه
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# ۴. بهبود اختیاری
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "رنگ بیشتری اضافه کنید و سرعت را کم کنید",
    "preferred_locale": "fa"
})
# job_id جدید را به همان روش بررسی کنید…

# ۵. افزودن صوت پس از بهبودها
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "fa"
})
# job_id جدید را بررسی کنید…

# ۶. بهبود اختیاری آموزش‌پذیری روایت
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": "fa"
})
# job_id جدید را بررسی کنید…
```