Навичка агента

# Навичка API DeepManim

Використовуйте API DeepManim, щоб створювати, покращувати й озвучувати анімовані пояснювальні відео з текстових запитів.

## Базовий 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 кредиту та залежать від пресету. Запити audio і improve-narration коштують 1 кредит. Читання даних безкоштовне.

## Кінцеві точки

### POST /generate
Створити нове відео з текстового запиту. Озвучення увімкнено за замовчуванням.

Тіло запиту:
```json
{
  "message": "Поясніть гравітацію",
  "session_id": null,
  "preferred_locale": "uk"
}
```
- `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": "uk"
}
```

Відповідь:
```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": "uk"
}
```

### POST /improve-narration
Покращити наявне озвучення відео.

Тіло запиту:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Зробіть пояснення зрозумілішим для початківців.",
  "preferred_locale": "uk"
}
```

### 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": "uk"
})
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": "uk"
})
# Перевіряйте новий 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": "uk"
})
# Перевіряти новий 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": "uk"
})
# Перевіряти новий job_id…
```