代理程式技能

# 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-TW"
}
```
- `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-TW"
}
```

回應:
```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-TW"
}
```

### POST /improve-narration
改善影片中現有的旁白。

請求本文:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "讓解釋對初學者更直觀。",
  "preferred_locale": "zh-TW"
}
```

### 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-TW"
})
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-TW"
})
# 以相同方式輪詢新的 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-TW"
})
# 輪詢新的 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-TW"
})
# 輪詢新的 job_id……
```