Compétence d’agent

# Compétence API DeepManim

Utilisez l’API DeepManim pour générer, améliorer et ajouter une narration à des vidéos explicatives animées à partir de prompts textuels.

## URL de base

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

## Authentification

Toutes les requêtes nécessitent une clé API dans l’en-tête Authorization :

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## Flux de travail

Le flux habituel est le suivant :

1. **Générez** une vidéo à partir d’un prompt avec `POST /generate`
2. **Vérifiez** le job renvoyé avec `GET /jobs/{job_id}` jusqu’à ce que `status` vaille `"completed"`
3. **Améliorez** la vidéo avec des instructions de suivi via `POST /improve` (facultatif et répétable)
4. **Ajoutez** la narration audio via `POST /audio` lorsque les visuels vous conviennent
5. **Améliorez la narration** via `POST /improve-narration` si nécessaire

Les appels de génération et d’amélioration commencent à 1,5 crédit et varient selon le preset. Les appels audio et improve-narration coûtent 1 crédit. La lecture des données est gratuite.

## Points d’accès

### POST /generate
Générer une vidéo à partir d’un prompt textuel. La narration audio est incluse par défaut.

Corps de la requête:
```json
{
  "message": "Expliquez le théorème de Pythagore",
  "session_id": null,
  "preferred_locale": "fr"
}
```
- `message` (required): Le prompt décrivant ce qu’il faut animer.
- `session_id` (optional): Transmettez un ID de session existant pour continuer une conversation.

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

### POST /improve
Améliorer ou modifier une vidéo existante. N’inclut PAS l’audio : ajoutez-le via /audio après toutes les modifications.

Corps de la requête:
```json
{
  "session_id": "def-456",
  "message": "Assombrissez l’arrière-plan et ralentissez l’animation",
  "preferred_locale": "fr"
}
```

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

### POST /audio
Ajouter une narration audio à une vidéo existante.

Corps de la requête:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "fr"
}
```

### POST /improve-narration
Améliorer la narration existante d’une vidéo.

Corps de la requête:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Rendez l’explication plus intuitive pour les débutants.",
  "preferred_locale": "fr"
}
```

### GET /jobs/{job_id}
Vérifier l’état d’un job. Le champ `phase` indique l’avancement : `brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

Réponse lorsque le job est terminé :

Réponse lorsque le job est terminé:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Une animation du théorème de Pythagore...",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "Quelles sont les applications concrètes ?"
  }
}
```

Valeurs possibles de `status` : `pending`, `running`, `completed`, `failed`.

### POST /jobs/{job_id}/cancel — Annuler un job en cours ou en attente.

### GET /sessions — Lister toutes vos sessions.

### GET /sessions/{session_id} — Obtenir une session avec tout l’historique des messages.

### DELETE /sessions/{session_id} — Supprimer une session et tous ses messages.

### GET /sessions/{session_id}/jobs
Lister les jobs d’une session. Paramètre de requête facultatif : `?status=completed`

### GET /messages/{message_id} — Obtenir un message par son ID.

### GET /credits
Obtenir le solde : `balance`, `total_used`, `total_purchased`, `plan`.

### GET /me
Obtenir les informations de l’utilisateur : `id`, `email`, `display_name`.

## Codes d’erreur

- `401` — Clé API manquante ou invalide
- `402` — Crédits insuffisants
- `404` — Ressource introuvable
- `400` — Requête invalide

## Stratégie de vérification

Les jobs prennent généralement 60 à 120 secondes. Vérifiez `GET /jobs/{job_id}` toutes les 3 à 5 secondes. Utilisez `estimated_time_remaining_seconds` pour ajuster la fréquence. Arrêtez lorsque `status` vaut `completed` ou `failed`.

## Exemple : flux complet

```python
import requests, time

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

# 1. Générer
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Expliquez la gravité",
    "preferred_locale": "fr"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

# 2. Vérifier jusqu’à la fin
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=headers).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(4)

# 3. Récupérer le résultat
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. Améliorer éventuellement
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Ajoutez davantage de couleurs et ralentissez l’animation",
    "preferred_locale": "fr"
})
# Vérifiez le nouveau job_id de la même manière…

# 5. Ajouter l’audio après les améliorations
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "fr"
})
# Vérifiez le nouveau job_id…

# 6. Améliorer éventuellement la pédagogie de la narration
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": "Rendez l’explication plus intuitive pour les débutants.",
  "preferred_locale": "fr"
})
# Vérifiez le nouveau job_id…
```