에이전트 스킬

# DeepManim API 스킬

DeepManim API를 사용하면 텍스트 프롬프트에서 애니메이션 설명 영상을 생성하고, 개선하고, 내레이션을 추가할 수 있습니다.

## 기본 URL

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

## 인증

모든 요청에는 Authorization 헤더에 API 키가 필요합니다:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## 작업 흐름

일반적인 작업 흐름은 다음과 같습니다:

1. 텍스트 프롬프트로 `POST /generate`를 호출해 동영상을 **생성**합니다
2. `status`가 `"completed"`가 될 때까지 반환된 작업을 `GET /jobs/{job_id}`로 **폴링**합니다
3. 후속 지시를 `POST /improve`로 보내 동영상을 **개선**합니다(선택 사항, 반복 가능)
4. 영상이 만족스러우면 `POST /audio`로 오디오 내레이션을 **추가**합니다
5. 필요하면 `POST /improve-narration`으로 **내레이션을 개선**합니다

생성 및 개선 호출은 1.5크레딧부터 시작하며 프리셋에 따라 달라집니다. 오디오 및 improve-narration 호출은 1크레딧입니다. 데이터 조회는 무료입니다.

## 엔드포인트

### POST /generate
텍스트 프롬프트로 새 동영상을 생성합니다. 오디오 내레이션은 기본으로 포함됩니다.

요청 본문:
```json
{
  "message": "중력을 설명해 주세요",
  "session_id": null,
  "preferred_locale": "ko"
}
```
- `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": "ko"
}
```

응답:
```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": "ko"
}
```

### POST /improve-narration
동영상의 기존 내레이션을 개선합니다.

요청 본문:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "초보자도 더 직관적으로 이해할 수 있게 설명해 주세요.",
  "preferred_locale": "ko"
}
```

### 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": "ko"
})
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": "ko"
})
# 새 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": "ko"
})
# 새 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": "ko"
})
# 새 job_id를 폴링…
```