Kỹ năng DeepManim

# Kỹ năng DeepManim

Tạo, cải thiện và thêm thuyết minh cho video giải thích hoạt họa bằng API DeepManim.

## URL cơ sở

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

## Xác thực

Gửi khóa API trong tiêu đề Authorization của mọi yêu cầu.

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## Quy trình

Mỗi video được tạo bất đồng bộ. Quy trình thông thường:

1. Gửi yêu cầu tạo
2. Thăm dò trạng thái tác vụ
3. Tải video khi hoàn tất
4. Cải thiện bằng yêu cầu tiếp theo
5. Thêm hoặc cải thiện thuyết minh

Mỗi thao tác tiêu tốn tín dụng theo độ phức tạp. Kiểm tra số dư trước khi bắt đầu.

## Các endpoint

### Tạo video
Bắt đầu một tác vụ tạo video mới.

Thân yêu cầu:
```json
{
  "message": "Giải thích lực hấp dẫn bằng một mô phỏng trực quan",
  "session_id": null,
  "preferred_locale": "vi"
}
```
- `message` (required): chủ đề hoặc câu hỏi cần trực quan hóa
- `session_id` (optional): ID phiên để tiếp tục cuộc trò chuyện hiện có

Phản hồi:
```json
{
  "job_id": "abc-123",
  "session_id": "def-456",
  "status": "pending"
}
```

### Cải thiện video
Gửi yêu cầu tiếp theo để sửa video trong một phiên.

Thân yêu cầu:
```json
{
  "session_id": "def-456",
  "message": "Làm nhãn rõ hơn và giảm tốc độ hoạt họa",
  "preferred_locale": "vi"
}
```

Phản hồi:
```json
{
  "job_id": "ghi-789",
  "session_id": "def-456",
  "status": "pending"
}
```

### Thêm âm thanh
Tạo thuyết minh cho video đã có.

Thân yêu cầu:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "vi"
}
```

### Cải thiện thuyết minh
Tạo lại thuyết minh mượt mà hơn hoặc theo hướng dẫn cụ thể.

Thân yêu cầu:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Nói tự nhiên, rõ ràng và giữ nhịp vừa phải",
  "preferred_locale": "vi"
}
```

### Tác vụ
Theo dõi tiến độ của các tác vụ tạo và hậu kỳ.

Các giai đoạn gồm khám phá ý tưởng, lên ý tưởng, xây dựng tầm nhìn, tinh chỉnh chi tiết, ghép các phần, đánh bóng, thêm giọng nói, lặp lại và hoàn tất.

Phản hồi khi hoàn tất:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Giải thích lực hấp dẫn bằng một mô phỏng trực quan",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "Nói tự nhiên, rõ ràng và giữ nhịp vừa phải"
  }
}
```

Trạng thái có thể là pending, running, completed hoặc failed.

### Hủy tác vụ

### Danh sách phiên

### Chi tiết phiên

### Xóa phiên

### Tác vụ trong phiên
Liệt kê mọi tác vụ thuộc một phiên.

### Tin nhắn

### Tín dụng
Xem số dư tín dụng hiện tại, tổng đã dùng và gói.

### Tài khoản hiện tại
Trả về thông tin người dùng của khóa API.

## Lỗi

- 401 — thiếu hoặc sai khóa API
- 402 — không đủ tín dụng
- 404 — không tìm thấy tài nguyên
- 422 — yêu cầu không hợp lệ

## Thăm dò

Thăm dò mỗi vài giây và dừng khi status là completed hoặc failed.

## Ví dụ hoàn chỉnh

```python
import requests, time

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

# Tạo video giải thích lực hấp dẫn
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Giải thích lực hấp dẫn bằng một mô phỏng trực quan",
    "preferred_locale": "vi"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

# Chờ đến khi tác vụ hoàn tất
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=headers).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(4)

# Lấy URL video và tin nhắn kết quả
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# Cải thiện video
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Làm nhãn rõ hơn và giảm tốc độ hoạt họa",
    "preferred_locale": "vi"
})
# Thăm dò tác vụ cải thiện

# Thêm thuyết minh
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "vi"
})
# Thăm dò tác vụ âm thanh

# Cải thiện thuyết minh
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": "Nói tự nhiên, rõ ràng và giữ nhịp vừa phải",
  "preferred_locale": "vi"
})
# Thăm dò tác vụ thuyết minh
```