Skill voor agents

# DeepManim API-skill

Gebruik de DeepManim API om vanuit tekstprompts geanimeerde uitlegvideo's te genereren, verbeteren en van voice-over te voorzien.

## Basis-URL

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

## Authenticatie

Voor elke aanvraag is een API-sleutel in de Authorization-header nodig:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## Werkwijze

De gebruikelijke werkwijze is:

1. **Genereer** een video vanuit een tekstprompt met `POST /generate`
2. **Vraag** de taak op met `GET /jobs/{job_id}` totdat `status` `"completed"` is
3. **Verbeter** de video met vervolgopdrachten via `POST /improve` (optioneel en herhaalbaar)
4. **Voeg** voice-over toe via `POST /audio` wanneer de beelden goed zijn
5. **Verbeter de voice-over** via `POST /improve-narration` als dat nodig is

Generatie- en verbeteringsaanvragen beginnen bij 1,5 credits en hangen af van de voorinstelling. Audio- en improve-narration-aanvragen kosten 1 credit. Gegevens lezen is gratis.

## Endpoints

### POST /generate
Genereer een nieuwe video vanuit een tekstprompt. Audio-voice-over wordt standaard toegevoegd.

Aanvraagbody:
```json
{
  "message": "Leg zwaartekracht uit",
  "session_id": null,
  "preferred_locale": "nl"
}
```
- `message` (required): De prompt die beschrijft wat moet worden geanimeerd.
- `session_id` (optional): Geef een bestaande session-ID mee om een gesprek voort te zetten.

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

### POST /improve
Verbeter of wijzig een bestaande video. Dit voegt GEEN audio toe — gebruik /audio nadat alle wijzigingen klaar zijn.

Aanvraagbody:
```json
{
  "session_id": "def-456",
  "message": "Voeg meer kleur toe en vertraag de animatie",
  "preferred_locale": "nl"
}
```

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

### POST /audio
Voeg audio-voice-over toe aan een bestaande video.

Aanvraagbody:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "nl"
}
```

### POST /improve-narration
Verbeter de bestaande voice-over van een video.

Aanvraagbody:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Maak de uitleg intuïtiever voor beginners.",
  "preferred_locale": "nl"
}
```

### GET /jobs/{job_id}
Controleer de taakstatus. Het veld `phase` geeft de voortgang aan: `brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

Antwoord wanneer de taak klaar is:

Antwoord na voltooiing:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Leg zwaartekracht uit",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "Maak de uitleg intuïtiever voor beginners."
  }
}
```

Mogelijke waarden van `status`: `pending`, `running`, `completed`, `failed`.

### POST /jobs/{job_id}/cancel — Annuleer een lopende of wachtende taak.

### GET /sessions — Bekijk al je sessies.

### GET /sessions/{session_id} — Haal een sessie met de volledige berichtgeschiedenis op.

### DELETE /sessions/{session_id} — Verwijder een sessie en al haar berichten.

### GET /sessions/{session_id}/jobs
Bekijk de taken van een sessie. Optionele queryparameter: `?status=completed`

### GET /messages/{message_id} — Haal één bericht op via de ID.

### GET /credits
Bekijk het creditsaldo: `balance`, `total_used`, `total_purchased`, `plan`.

### GET /me
Bekijk gebruikersgegevens: `id`, `email`, `display_name`.

## Foutcodes

- `401` — Ontbrekende of ongeldige API-sleutel
- `402` — Onvoldoende credits
- `404` — Bron niet gevonden
- `400` — Ongeldige aanvraag

## Pollingstrategie

Taken duren meestal 60–120 seconden. Vraag `GET /jobs/{job_id}` elke 3–5 seconden op. Gebruik `estimated_time_remaining_seconds` om de frequentie aan te passen. Stop wanneer `status` `completed` of `failed` is.

## Voorbeeld: volledige workflow

```python
import requests, time

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

# 1. Genereren
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Leg zwaartekracht uit",
    "preferred_locale": "nl"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

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

# 3. Resultaat ophalen
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. Optioneel verbeteren
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Voeg meer kleur toe en vertraag de animatie",
    "preferred_locale": "nl"
})
# Vraag de nieuwe job_id op dezelfde manier op…

# 5. Audio toevoegen na de verbeteringen
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "nl"
})
# Vraag de nieuwe job_id op…

# 6. Voice-over optioneel didactischer maken
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": "Maak de uitleg intuïtiever voor beginners.",
  "preferred_locale": "nl"
})
# Vraag de nieuwe job_id op…
```