智能体技能

# DeepManim API 技能

你可以使用 DeepManim API，根据文字提示词生成、改进并为动画解释视频添加旁白。

## 基础 URL

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

## 身份验证

所有请求都需要在 Authorization 请求头中提供 API 密钥：

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## 工作流程

典型流程如下：

1. **生成**：通过 `POST /generate` 从文字提示词生成视频
2. **轮询**：通过 `GET /jobs/{job_id}` 轮询返回的任务，直到 `status` 为 `"completed"`
3. **改进**：通过 `POST /improve` 使用后续指令改进视频（可选且可重复）
4. **添加音频**：对视觉效果满意后，通过 `POST /audio` 添加旁白
5. **改进旁白**：需要时通过 `POST /improve-narration` 改进旁白

生成和改进调用最低 1.5 点数，具体费用取决于预设。音频和 improve-narration 调用每次 1 点数。读取数据免费。

## 端点

### POST /generate
从文字提示词生成新视频，默认包含音频旁白。

请求正文:
```json
{
  "message": "解释重力",
  "session_id": null,
  "preferred_locale": "zh-CN"
}
```
- `message` (required): 描述要制作什么动画的提示词。
- `session_id` (optional): 传入已有会话 ID 以继续对话。

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

### POST /improve
改进或修改现有视频。不包含音频——完成所有修改后，请通过 /audio 单独添加。

请求正文:
```json
{
  "session_id": "def-456",
  "message": "添加更多颜色，并放慢动画",
  "preferred_locale": "zh-CN"
}
```

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

### POST /audio
为现有视频添加音频旁白。

请求正文:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "zh-CN"
}
```

### POST /improve-narration
改进视频中现有的旁白。

请求正文:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "让解释对初学者更直观。",
  "preferred_locale": "zh-CN"
}
```

### GET /jobs/{job_id}
轮询任务状态。`phase` 字段表示进度：`brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

完成时的响应：

完成时的响应:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "解释重力",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "让解释对初学者更直观。"
  }
}
```

可能的 `status` 值：`pending`、`running`、`completed`、`failed`。

### POST /jobs/{job_id}/cancel —— 取消正在运行或等待中的任务。

### GET /sessions —— 列出所有会话。

### GET /sessions/{session_id} —— 获取包含完整消息历史的会话。

### DELETE /sessions/{session_id} —— 删除会话及其所有消息。

### GET /sessions/{session_id}/jobs
列出会话的任务。可选查询参数：`?status=completed`

### GET /messages/{message_id} —— 按 ID 获取单条消息。

### GET /credits
获取点数余额：`balance`、`total_used`、`total_purchased`、`plan`。

### GET /me
获取当前用户信息：`id`、`email`、`display_name`。

## 错误代码

- `401` —— 缺少或无效的 API 密钥
- `402` —— 点数不足
- `404` —— 未找到资源
- `400` —— 请求无效

## 轮询策略

任务通常需要 60–120 秒。每隔 3–5 秒轮询 `GET /jobs/{job_id}`。使用 `estimated_time_remaining_seconds` 调整轮询频率。`status` 为 `completed` 或 `failed` 时停止。

## 示例：完整流程

```python
import requests, time

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

# 1. 生成
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "解释重力",
    "preferred_locale": "zh-CN"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

# 2. 轮询直到完成
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=headers).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(4)

# 3. 获取结果
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. 可选：改进
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "添加更多颜色，并放慢动画",
    "preferred_locale": "zh-CN"
})
# 以相同方式轮询新的 job_id……

# 5. 改进后添加音频
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "zh-CN"
})
# 轮询新的 job_id……

# 6. 可选：改进旁白的教学效果
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": "让解释对初学者更直观。",
  "preferred_locale": "zh-CN"
})
# 轮询新的 job_id……
```