ทักษะสำหรับเอเจนต์

# ทักษะ API ของ DeepManim

คุณสามารถใช้ API ของ DeepManim เพื่อสร้าง ปรับปรุง และเพิ่มเสียงบรรยายให้วิดีโออธิบายแบบแอนิเมชันจากพรอมต์ข้อความ

## URL หลัก

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

## การยืนยันตัวตน

คำขอทั้งหมดต้องมีคีย์ API ในส่วนหัว Authorization:

```
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 เครดิตและเปลี่ยนไปตามค่าที่ตั้งไว้ การเรียก audio และ improve-narration ใช้ 1 เครดิต การอ่านข้อมูลไม่มีค่าใช้จ่าย

## ปลายทาง API

### POST /generate
สร้างวิดีโอใหม่จากพรอมต์ข้อความ โดยค่าเริ่มต้นจะมีเสียงบรรยายรวมอยู่ด้วย

เนื้อหาคำขอ:
```json
{
  "message": "อธิบายแรงโน้มถ่วง",
  "session_id": null,
  "preferred_locale": "th"
}
```
- `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": "th"
}
```

คำตอบ:
```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": "th"
}
```

### POST /improve-narration
ปรับปรุงเสียงบรรยายเดิมของวิดีโอ

เนื้อหาคำขอ:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "ทำให้คำอธิบายเข้าใจง่ายขึ้นสำหรับผู้เริ่มต้น",
  "preferred_locale": "th"
}
```

### 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 วินาที ตรวจสอบ GET /jobs/{job_id} ทุก 3–5 วินาที ใช้ 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": "th"
})
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": "th"
})
# ตรวจสอบ 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": "th"
})
# ตรวจสอบ 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": "th"
})
# ตรวจสอบ job_id ใหม่…
```