エージェントスキル

# 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クレジットからで、プリセットにより変わります。audioとimprove-narrationは1クレジットです。データの読み取りは無料です。

## エンドポイント

### POST /generate
テキストプロンプトから新しい動画を生成します。音声ナレーションはデフォルトで含まれます。

リクエストボディ:
```json
{
  "message": "重力を説明して",
  "session_id": null,
  "preferred_locale": "ja"
}
```
- `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": "ja"
}
```

レスポンス:
```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": "ja"
}
```

### POST /improve-narration
動画にあるナレーションを改善します。

リクエストボディ:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "初心者にも直感的な説明にして。",
  "preferred_locale": "ja"
}
```

### 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": "ja"
})
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": "ja"
})
# 同様に新しい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": "ja"
})
# 新しい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": "ja"
})
# 新しいjob_idをポーリング…
```