Skill per agenti

# Skill API DeepManim

Puoi usare l’API DeepManim per generare, migliorare e narrare video esplicativi animati a partire da prompt testuali.

## URL di base

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

## Autenticazione

Tutte le richieste richiedono una chiave API nell’header Authorization:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## Flusso di lavoro

Il flusso tipico è:

1. **Genera** un video da un prompt testuale tramite `POST /generate`
2. **Controlla** il job restituito con `GET /jobs/{job_id}` finché `status` non è `"completed"`
3. **Migliora** il video con istruzioni successive tramite `POST /improve` (facoltativo e ripetibile)
4. **Aggiungi** la narrazione tramite `POST /audio` quando gli elementi visivi ti soddisfano
5. **Migliora la narrazione** tramite `POST /improve-narration` se necessario

Le chiamate di generazione e miglioramento partono da 1,5 crediti e variano in base al preset. Le chiamate audio e improve-narration costano 1 credito. La lettura dei dati è gratuita.

## Endpoint

### POST /generate
Genera un nuovo video da un prompt testuale. La narrazione audio è inclusa per impostazione predefinita.

Corpo della richiesta:
```json
{
  "message": "Spiega il teorema di Pitagora",
  "session_id": null,
  "preferred_locale": "it"
}
```
- `message` (required): Il prompt che descrive cosa animare.
- `session_id` (optional): Passa un ID sessione esistente per continuare una conversazione.

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

### POST /improve
Migliora o modifica un video esistente. NON include l’audio: aggiungilo tramite /audio dopo tutte le modifiche.

Corpo della richiesta:
```json
{
  "session_id": "def-456",
  "message": "Rendi lo sfondo più scuro e rallenta l’animazione",
  "preferred_locale": "it"
}
```

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

### POST /audio
Aggiungi la narrazione audio a un video esistente.

Corpo della richiesta:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "it"
}
```

### POST /improve-narration
Migliora la narrazione esistente di un video.

Corpo della richiesta:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Rendi la spiegazione più intuitiva per i principianti.",
  "preferred_locale": "it"
}
```

### GET /jobs/{job_id}
Controlla lo stato del job. Il campo `phase` indica l’avanzamento: `brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

Risposta al completamento:

Risposta al completamento:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Un’animazione del teorema di Pitagora...",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "Quali sono alcune applicazioni nella vita reale?"
  }
}
```

Valori possibili di `status`: `pending`, `running`, `completed`, `failed`.

### POST /jobs/{job_id}/cancel — Annulla un job in esecuzione o in attesa.

### GET /sessions — Elenca tutte le tue sessioni.

### GET /sessions/{session_id} — Ottieni una sessione con la cronologia completa dei messaggi.

### DELETE /sessions/{session_id} — Elimina una sessione e tutti i suoi messaggi.

### GET /sessions/{session_id}/jobs
Elenca i job di una sessione. Parametro query facoltativo: `?status=completed`

### GET /messages/{message_id} — Ottieni un messaggio tramite ID.

### GET /credits
Ottieni il saldo: `balance`, `total_used`, `total_purchased`, `plan`.

### GET /me
Ottieni le informazioni dell’utente: `id`, `email`, `display_name`.

## Codici di errore

- `401` — Chiave API mancante o non valida
- `402` — Crediti insufficienti
- `404` — Risorsa non trovata
- `400` — Richiesta non valida

## Strategia di polling

I job richiedono in genere 60–120 secondi. Esegui il polling di `GET /jobs/{job_id}` ogni 3–5 secondi. Usa `estimated_time_remaining_seconds` per regolare la frequenza. Interrompi quando `status` è `completed` o `failed`.

## Esempio: flusso completo

```python
import requests, time

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

# 1. Genera
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Spiega la gravità",
    "preferred_locale": "it"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

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

# 3. Ottieni il risultato
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. Migliora facoltativamente
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Aggiungi più colore e rallenta l’animazione",
    "preferred_locale": "it"
})
# Esegui il polling del nuovo job_id allo stesso modo…

# 5. Aggiungi l’audio dopo i miglioramenti
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "it"
})
# Esegui il polling del nuovo job_id…

# 6. Migliora facoltativamente la pedagogia della narrazione
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": "Rendi la spiegazione più intuitiva per i principianti.",
  "preferred_locale": "it"
})
# Esegui il polling del nuovo job_id…
```