Umiejętność agenta

# Umiejętność API DeepManim

Możesz używać API DeepManim do generowania, ulepszania i opatrywania narracją animowanych filmów wyjaśniających na podstawie promptów tekstowych.

## Podstawowy adres URL

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

## Uwierzytelnianie

Każde żądanie wymaga klucza API w nagłówku Authorization:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## Przebieg pracy

Typowy przebieg wygląda tak:

1. **Wygeneruj** film na podstawie promptu tekstowego przez `POST /generate`
2. **Sprawdzaj** zwrócone zadanie przez `GET /jobs/{job_id}`, aż `status` zmieni się na `"completed"`
3. **Ulepsz** film kolejnymi instrukcjami przez `POST /improve` (opcjonalnie, wielokrotnie)
4. **Dodaj** narrację przez `POST /audio`, gdy wygląd filmu Ci odpowiada
5. **Ulepsz narrację** przez `POST /improve-narration`, jeśli to potrzebne

Wywołania generowania i ulepszania kosztują od 1,5 kredytu, zależnie od presetu. Wywołania audio i improve-narration kosztują 1 kredyt. Odczytywanie danych jest bezpłatne.

## Punkty końcowe

### POST /generate
Wygeneruj nowy film na podstawie promptu tekstowego. Narracja dźwiękowa jest domyślnie dołączona.

Treść żądania:
```json
{
  "message": "Wyjaśnij grawitację",
  "session_id": null,
  "preferred_locale": "pl"
}
```
- `message` (required): Prompt opisujący, co ma zostać zanimowane.
- `session_id` (optional): Przekaż istniejący identyfikator sesji, aby kontynuować rozmowę.

Odpowiedź:
```json
{
  "job_id": "abc-123",
  "session_id": "def-456",
  "status": "pending"
}
```

### POST /improve
Ulepsz lub zmodyfikuj istniejący film. NIE zawiera dźwięku — dodaj go osobno przez /audio po zakończeniu modyfikacji.

Treść żądania:
```json
{
  "session_id": "def-456",
  "message": "Dodaj więcej kolorów i zwolnij animację",
  "preferred_locale": "pl"
}
```

Odpowiedź:
```json
{
  "job_id": "ghi-789",
  "session_id": "def-456",
  "status": "pending"
}
```

### POST /audio
Dodaj narrację dźwiękową do istniejącego filmu.

Treść żądania:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "pl"
}
```

### POST /improve-narration
Ulepsz istniejącą narrację filmu.

Treść żądania:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Uczyń wyjaśnienie bardziej intuicyjnym dla początkujących.",
  "preferred_locale": "pl"
}
```

### GET /jobs/{job_id}
Sprawdzaj stan zadania. Pole `phase` pokazuje postęp: `brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

Odpowiedź po zakończeniu:

Odpowiedź po zakończeniu:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Wyjaśnij grawitację",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "Uczyń wyjaśnienie bardziej intuicyjnym dla początkujących."
  }
}
```

Możliwe wartości `status`: `pending`, `running`, `completed`, `failed`.

### POST /jobs/{job_id}/cancel — Anuluj działające lub oczekujące zadanie.

### GET /sessions — Wyświetl wszystkie swoje sesje.

### GET /sessions/{session_id} — Pobierz sesję z pełną historią wiadomości.

### DELETE /sessions/{session_id} — Usuń sesję i wszystkie jej wiadomości.

### GET /sessions/{session_id}/jobs
Wyświetl zadania sesji. Opcjonalny parametr zapytania: `?status=completed`

### GET /messages/{message_id} — Pobierz pojedynczą wiadomość po identyfikatorze.

### GET /credits
Pobierz saldo kredytów: `balance`, `total_used`, `total_purchased`, `plan`.

### GET /me
Pobierz informacje o bieżącym użytkowniku: `id`, `email`, `display_name`.

## Kody błędów

- `401` — Brak klucza API lub klucz jest nieprawidłowy
- `402` — Niewystarczająca liczba kredytów
- `404` — Nie znaleziono zasobu
- `400` — Nieprawidłowe żądanie

## Strategia odpytywania

Zadania zwykle trwają 60–120 sekund. Odpytywanie `GET /jobs/{job_id}` wykonuj co 3–5 sekund. Użyj pola `estimated_time_remaining_seconds`, aby dostosować częstotliwość. Przestań odpytywać, gdy `status` będzie równe `completed` lub `failed`.

## Przykład: pełny przebieg

```python
import requests, time

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

# 1. Generowanie
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Wyjaśnij grawitację",
    "preferred_locale": "pl"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

# 2. Odpytywanie do zakończenia
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=headers).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(4)

# 3. Pobranie wyniku
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. Opcjonalne ulepszenie
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Dodaj więcej kolorów i zwolnij animację",
    "preferred_locale": "pl"
})
# Odpytywanie nowego job_id w ten sam sposób…

# 5. Dodanie dźwięku po ulepszeniach
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "pl"
})
# Odpytywanie nowego job_id…

# 6. Opcjonalne ulepszenie dydaktyki narracji
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": "Uczyń wyjaśnienie bardziej intuicyjnym dla początkujących.",
  "preferred_locale": "pl"
})
# Odpytywanie nowego job_id…
```