Habilidad para agentes

# Habilidad de API de DeepManim

Puedes usar la API de DeepManim para generar, mejorar y narrar vídeos explicativos animados a partir de prompts de texto.

## URL base

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

## Autenticación

Todas las solicitudes requieren una clave API en la cabecera Authorization:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## Flujo de trabajo

El flujo habitual es:

1. **Genera** un vídeo desde un prompt mediante `POST /generate`
2. **Consulta** el trabajo devuelto mediante `GET /jobs/{job_id}` hasta que `status` sea `"completed"`
3. **Mejora** el vídeo con instrucciones posteriores mediante `POST /improve` (opcional y repetible)
4. **Añade** narración mediante `POST /audio` cuando estés satisfecho con los elementos visuales
5. **Mejora la narración** mediante `POST /improve-narration` si es necesario

Las llamadas de generación y mejora empiezan en 1,5 créditos y varían según el preset. Las llamadas de audio y improve-narration cuestan 1 crédito. Leer datos es gratis.

## Endpoints

### POST /generate
Genera un vídeo nuevo desde un prompt de texto. La narración de audio se incluye de forma predeterminada.

Cuerpo de la solicitud:
```json
{
  "message": "Explica el teorema de Pitágoras",
  "session_id": null,
  "preferred_locale": "es"
}
```
- `message` (required): El prompt que describe qué animar.
- `session_id` (optional): Pasa un ID de sesión existente para continuar una conversación.

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

### POST /improve
Mejora o modifica un vídeo existente. NO incluye audio: añádelo mediante /audio después de todas las modificaciones.

Cuerpo de la solicitud:
```json
{
  "session_id": "def-456",
  "message": "Oscurece el fondo y ralentiza la animación",
  "preferred_locale": "es"
}
```

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

### POST /audio
Añade narración de audio a un vídeo existente.

Cuerpo de la solicitud:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "es"
}
```

### POST /improve-narration
Mejora la narración existente de un vídeo.

Cuerpo de la solicitud:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Haz que la explicación sea más intuitiva para principiantes.",
  "preferred_locale": "es"
}
```

### GET /jobs/{job_id}
Consulta el estado del trabajo. El campo `phase` indica el progreso: `brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

Respuesta cuando termina:

Respuesta cuando termina:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Una animación del teorema de Pitágoras...",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "¿Cuáles son algunas aplicaciones en el mundo real?"
  }
}
```

Valores posibles de `status`: `pending`, `running`, `completed`, `failed`.

### POST /jobs/{job_id}/cancel — Cancela un trabajo en curso o pendiente.

### GET /sessions — Lista todas tus sesiones.

### GET /sessions/{session_id} — Obtén una sesión con todo el historial de mensajes.

### DELETE /sessions/{session_id} — Elimina una sesión y todos sus mensajes.

### GET /sessions/{session_id}/jobs
Lista los trabajos de una sesión. Parámetro opcional: `?status=completed`

### GET /messages/{message_id} — Obtén un mensaje por ID.

### GET /credits
Obtén el saldo: `balance`, `total_used`, `total_purchased`, `plan`.

### GET /me
Obtén la información del usuario: `id`, `email`, `display_name`.

## Códigos de error

- `401` — Falta la clave API o no es válida
- `402` — Créditos insuficientes
- `404` — Recurso no encontrado
- `400` — Solicitud no válida

## Estrategia de consulta

Los trabajos suelen tardar entre 60 y 120 segundos. Consulta `GET /jobs/{job_id}` cada 3–5 segundos. Usa `estimated_time_remaining_seconds` para ajustar la frecuencia. Detén las consultas cuando `status` sea `completed` o `failed`.

## Ejemplo: flujo 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. Generar
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Explica la gravedad",
    "preferred_locale": "es"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

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

# 3. Obtener el resultado
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. Mejorar opcionalmente
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Añade más color y hazlo más lento",
    "preferred_locale": "es"
})
# Consulta el nuevo job_id de la misma manera…

# 5. Añadir audio después de las mejoras
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "es"
})
# Consulta el nuevo job_id…

# 6. Mejorar opcionalmente la pedagogía de la narración
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": "Haz que la explicación sea más intuitiva para principiantes.",
  "preferred_locale": "es"
})
# Consulta el nuevo job_id…
```