# HeyGen連携プラグイン設計

学習管理サイトからHeyGenへ動画生成を依頼し、完成した動画URLを教材に登録するための設計です。

## 連携方針

HeyGenのAPIキーは、ブラウザ側には置かない。

学習サイトは、自前サーバーのプラグインAPIへ「この教材を動画化して」と依頼する。プラグインAPIがHeyGenへリクエストし、生成状況を管理する。

```text
学習管理サイト
↓
自前サーバーのHeyGenプラグイン
↓
HeyGen API
↓
完成動画URL
↓
教材へ登録
```

## 使うHeyGen API

### 認証

```http
X-Api-Key: <HEYGEN_API_KEY>
```

APIキーは `.env` やサーバー環境変数で管理する。

### 動画生成

```http
POST https://api.heygen.com/v2/video/generate
```

このエンドポイントは、アバター、音声、背景、スクリプトを含むシーン配列を送って動画生成を開始する。

### ステータス確認

生成後に返る `video_id` を使って、動画の状態を確認する。

状態は主に次のように扱う。

- `pending`
- `waiting`
- `processing`
- `completed`
- `failed`

### Webhook

大量生成ではWebhook利用がおすすめ。

HeyGenから `avatar_video.success` や `avatar_video.fail` を受け取り、生成結果を学習サイト側へ反映する。

## MVPで作るプラグインAPI

### 1. 動画生成ジョブ作成

```http
POST /api/plugins/heygen/video-jobs
```

```json
{
  "lessonId": "mail",
  "title": "メール文をAIと一緒に作る",
  "script": "今日は、AIを使ってメール文を作る練習をします。",
  "avatarId": "YOUR_AVATAR_ID",
  "voiceId": "YOUR_VOICE_ID"
}
```

レスポンス:

```json
{
  "jobId": "local-job-001",
  "provider": "heygen",
  "providerVideoId": "heygen-video-id",
  "status": "processing"
}
```

### 2. 生成状況取得

```http
GET /api/plugins/heygen/video-jobs/local-job-001
```

レスポンス:

```json
{
  "jobId": "local-job-001",
  "status": "completed",
  "videoUrl": "https://..."
}
```

### 3. Webhook受信

```http
POST /api/plugins/heygen/webhook
```

受け取った `video_id` と `url` を、ローカルの生成ジョブに紐づける。

## HeyGenへ送るデータの考え方

### アバター動画

教材の冒頭や短い説明に向いている。

```json
{
  "title": "メール文をAIと一緒に作る",
  "caption": true,
  "callback_id": "lesson-mail-job-001",
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "YOUR_AVATAR_ID"
      },
      "voice": {
        "type": "text",
        "input_text": "今日は、AIを使ってメール文を作る練習をします。",
        "voice_id": "YOUR_VOICE_ID",
        "speed": 0.9
      },
      "background": {
        "type": "color",
        "value": "#F5F7FA"
      }
    }
  ],
  "dimension": {
    "width": 1280,
    "height": 720
  }
}
```

### 教材大量生成での使い分け

- スライド型動画: 本編教材向け
- HeyGenアバター動画: 冒頭説明、導入、振り返り、案内動画向け
- HeyGenテンプレート: 同じ構成の動画を大量差し替えする場合に向く

## 学習サイト側の画面

動画生成タブに次を追加する。

- 生成方式: スライド型 / HeyGenアバター
- アバターID
- 音声ID
- 字幕ON/OFF
- 生成ジョブ作成
- HeyGen video_id
- 完成URL
- 教材へ登録

## 本番までの手順

1. HeyGenでAPIキーを取得
2. Avatars APIで `avatar_id` を確認
3. Voices APIで `voice_id` を確認
4. 自前サーバーへ `HEYGEN_API_KEY` を設定
5. プラグインAPIからHeyGenへ動画生成リクエスト
6. ステータス取得またはWebhookで完成検知
7. 完成動画URLを教材へ登録

## 注意点

- APIキーをHTMLやJavaScriptに書かない
- 利用者さんの個人情報をHeyGenへ送らない
- 動画URLは期限付きの場合があるため、必要なら自前ストレージへ保存する
- 公開前に支援員が内容を確認する
- 大量生成ではクレジット消費と上限を確認する