Skill para agentes

# Skill da API DeepManim

Você pode usar a API DeepManim para gerar, melhorar e narrar vídeos explicativos animados a partir de prompts de texto.

## URL base

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

## Autenticação

Todas as requisições exigem uma chave de API no cabeçalho Authorization:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## Fluxo de trabalho

O fluxo típico é:

1. **Gere** um vídeo a partir de um prompt usando `POST /generate`
2. **Consulte** o job retornado via `GET /jobs/{job_id}` até que `status` seja `"completed"`
3. **Melhore** o vídeo com instruções adicionais via `POST /improve` (opcional e repetível)
4. **Adicione** narração via `POST /audio` quando estiver satisfeito com os visuais
5. **Melhore a narração** via `POST /improve-narration` se necessário

As chamadas de geração e melhoria começam em 1,5 créditos e variam conforme o preset. As chamadas de áudio e improve-narration custam 1 crédito. A leitura de dados é gratuita.

## Endpoints

### POST /generate
Gere um vídeo novo a partir de um prompt de texto. A narração em áudio é incluída por padrão.

Corpo da requisição:
```json
{
  "message": "Explique o teorema de Pitágoras",
  "session_id": null,
  "preferred_locale": "pt-BR"
}
```
- `message` (required): O prompt que descreve o que deve ser animado.
- `session_id` (optional): Passe um ID de sessão existente para continuar uma conversa.

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

### POST /improve
Melhore ou modifique um vídeo existente. NÃO inclui áudio — adicione-o via /audio após todas as modificações.

Corpo da requisição:
```json
{
  "session_id": "def-456",
  "message": "Deixe o fundo mais escuro e diminua a velocidade da animação",
  "preferred_locale": "pt-BR"
}
```

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

### POST /audio
Adicione narração em áudio a um vídeo existente.

Corpo da requisição:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "pt-BR"
}
```

### POST /improve-narration
Melhore a narração existente de um vídeo.

Corpo da requisição:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Torne a explicação mais intuitiva para iniciantes.",
  "preferred_locale": "pt-BR"
}
```

### GET /jobs/{job_id}
Consulte o status do job. O campo `phase` indica o progresso: `brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

Resposta quando concluído:

Resposta quando concluído:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Uma animação do teorema de Pitágoras...",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "Quais são algumas aplicações no mundo real?"
  }
}
```

Valores possíveis de `status`: `pending`, `running`, `completed`, `failed`.

### POST /jobs/{job_id}/cancel — Cancele um job em andamento ou pendente.

### GET /sessions — Liste todas as suas sessões.

### GET /sessions/{session_id} — Obtenha uma sessão com o histórico completo de mensagens.

### DELETE /sessions/{session_id} — Exclua uma sessão e todas as suas mensagens.

### GET /sessions/{session_id}/jobs
Liste os jobs de uma sessão. Parâmetro opcional: `?status=completed`

### GET /messages/{message_id} — Obtenha uma mensagem pelo ID.

### GET /credits
Obtenha o saldo de créditos: `balance`, `total_used`, `total_purchased`, `plan`.

### GET /me
Obtenha os dados do usuário: `id`, `email`, `display_name`.

## Códigos de erro

- `401` — Chave de API ausente ou inválida
- `402` — Créditos insuficientes
- `404` — Recurso não encontrado
- `400` — Requisição inválida

## Estratégia de consulta

Os jobs normalmente levam de 60 a 120 segundos. Consulte `GET /jobs/{job_id}` a cada 3–5 segundos. Use `estimated_time_remaining_seconds` para ajustar a frequência. Pare quando `status` for `completed` ou `failed`.

## Exemplo: fluxo 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. Gerar
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Explique a gravidade",
    "preferred_locale": "pt-BR"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

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

# 3. Obter o resultado
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. Melhorar opcionalmente
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Adicione mais cores e deixe mais lento",
    "preferred_locale": "pt-BR"
})
# Consulte o novo job_id da mesma forma…

# 5. Adicionar áudio após as melhorias
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "pt-BR"
})
# Consulte o novo job_id…

# 6. Melhorar opcionalmente a pedagogia da narração
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": "Torne a explicação mais intuitiva para iniciantes.",
  "preferred_locale": "pt-BR"
})
# Consulte o novo job_id…
```