HeyGen MP3 → MP4 (単一目的)
1つのMP3音声ファイルを受け取り、1つのHeyGenアバターリップシンクMP4を返します。それ以外は行いません。
このスキルが存在する理由は、既存のheygen-short-videoスキルが完全な制作計画・SRT・チャンク分割を必要とし、ユーザーが完成した音声だけを持っていてトーキングヘッド動画を生成したい場合に過剰だったからです。
なぜハイブリッドREST + MCPなのか（MCPのみではないのか）
このスキルの初期バージョンでは「MCPのみ——RESTは絶対に呼ばない」というルールを強制していましたが、2026年のHeyGen MCP再編により、そのルールはもはや実現不可能です。MCPサーバーはcreate_video_from_avatar、get_video、create_lipsync、list_avatar_looksなどを公開していますが、アセットアップロードツールはもう存在しません。ローカルのMP3からリップシンクを行うには、APIは依然としてaudioAssetId（アップロード済みアセット）またはaudioUrl（公開HTTPS URL）を必要とします。公開URLをホストするのは脆弱（リンク切れ、漏洩のリスク）なため、薄いヘルパーを介して文書化されたRESTアップロードエンドポイントを使用し、その後、動画作成、ポーリング、ダウンロードはMCP経由で続行します。
ハード制約
| 制約 | 許可される値 |
|---|---|
| アセットアップロード | REST POST https://upload.heygen.com/v1/asset（scripts/upload_asset.py経由、HEYGEN_API_KEYを使用） |
| 動画作成・ステータス・一覧 | HeyGen MCPのみ（mcp__heygen__create_video_from_avatar、mcp__heygen__get_video） |
| アバタールックID | HEYGEN_AVATAR_LOOKS環境変数（カンマ区切りの許可リスト）内のいずれかのID |
| ボイスID（MCPパスがTTSを強制する場合のみ） | .envのHEYGEN_VOICE_ID（他のボイスIDは許可されません） |
| MP3の長さ | ≤ 300秒（5分）。長い場合はすぐに失敗します。自動分割は行いません |
| アスペクト比（MCP enum） | デフォルトは9:16（TikTok / Reels）。親オーケストレーターが上書きした場合のみ16:9 |
| 解像度（MCP enum） | デフォルトは720p（9:16の場合は720×1280、16:9の場合は1280×720） |
MP3リップシンクの場合、音声タイプはaudioでaudioAssetIdが指定されます——voiceIdは送信されません。上記のvoice_id許可リストは、将来のMCPシグネチャで一つが必要になった場合にのみ関係します。
入力
- MP3パス（必須）——音声ファイルへの絶対パス。
- アバタールックID（オプション）——許可されたIDのいずれか。省略した場合は、許可セットからランダムに選択され、実行ごとに視覚的なバリエーションが生まれます。
- 出力パス（オプション）——デフォルトはプロジェクトルートからの相対パス
workspace/heygen-clips/<mp3-stem>/<mp3-stem>_<YYYYMMDD-HHMMSS>.mp4。 - アスペクト比（オプション）——
9:16（デフォルト）または16:9。
ワークフロー
以下の手順を順に実行します。各手順には停止条件があります。失敗した手順を超えて進めないでください。
0. 認証チェック（最初の呼び出しのみ）
HeyGen MCPサーバーはOAuthを使用します。新しいセッションではmcp__heygen__authenticateとmcp__heygen__complete_authenticationのみが公開されており、実際のツール（create_video_from_avatar、get_videoなど）は認証完了後に出現します。セッションにこれらのツールがロードされていない場合は、mcp__heygen__authenticateを呼び出し、返された認証URLをユーザーに提示します。ユーザーがクリックすると、ブラウザにlocalhostコールバックの「接続エラー」が表示される場合があります（これは想定内です）。ユーザーが完全なコールバックURLを貼り付け、あなたがmcp__heygen__complete_authenticationを呼び出します。認証後のツールが延期ツールリストに表示されたら、続行します。
1. MP3を検証する
uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py "<mp3_path>"
OK <seconds> / TOO_LONG <seconds> / MISSING を出力します。終了コード0 = OK、0以外 = 停止。
TOO_LONGの場合：ユーザーに長さと、HeyGenが単一動画を約5分に制限していることを伝え、既存の heygen-short-video スキル（チャンク分割を行う）を提案します。続行しないでください。
2. アバタールックを選択する
HEYGEN_AVATAR_LOOKS（カンマ区切り許可リスト）を読み取ります：
HEYGEN_AVATAR_LOOKS=$(
grep -h '^HEYGEN_AVATAR_LOOKS=' .env.local .env 2>/dev/null \
| head -1 | cut -d'=' -f2- | tr -d '"' | tr -d "'"
)
echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'
プレースホルダーの落とし穴 — claudeclaw-os/.env.local にはプレースホルダースタブ（avatar_look_id_1,avatar_look_id_2）が含まれています。実際の値は多くの場合 ~/Documents/GitHub/hoang-ai-marketing/.env にあります：
grep '^HEYGEN_AVATAR_LOOKS=' ~/Documents/GitHub/hoang-ai-marketing/.env
値が ^(your_|avatar_look_id_|placeholder) に一致する場合、欠落しているものとして扱い、マーケティングリポジトリの .env にフォールバックします。両方がプレースホルダー/欠落の場合は停止し、ユーザーに実際のIDを入力するよう求めます。
続行する前に、選択したアバタールックをユーザーに伝えてください——ユーザーが上書きしたい場合があります。
3. MP3をHeyGenアセットとしてアップロードする（REST）
uv run .claude/skills/heygen-mp3-to-mp4/scripts/upload_asset.py "<mp3_path>"
# → 成功時に "OK <asset_id>" を出力
ヘルパーはX-Api-Keyヘッダーを処理し、音声拡張子に適したContent-Typeを選択し、HEYGEN_API_KEYを次の順序で解決します：--key-fileフラグ → HEYGEN_API_KEY環境変数 → .env.local → .env → ~/Documents/GitHub/hoang-ai-marketing/.env。プレースホルダースタブ（your_*）は自動的にスキップされます。
標準出力に出力されたasset_idを取得します。
4. アバター動画を生成する（MCP）
新しいスキーマで mcp__heygen__create_video_from_avatar を呼び出します（古い dimension: {width, height} 形式は廃止されました——ツールは現在 aspectRatio enum + resolution enum を受け取ります）：
avatarId: <選択した許可リストのID>
audioAssetId: <ステップ3のもの>
aspectRatio: "9:16" # または親が上書きした場合は "16:9"
resolution: "720p" # 720p · 1080p · 4k
title: "<mp3-stem>-<timestamp>"
返された video_id を取得します（ステータスは最初 waiting になります）。
なぜaudio（テキストではないのか）： 既存のMP3からのリップシンクでは、HeyGenが音声を直接消費する必要があります。ここで script + voiceId を送信すると、HeyGenがTTSモードに切り替わり、アップロードされたMP3を完全に無視します。
5. 完了するまでポーリングする
mcp__heygen__get_video を video_id で約10～15秒ごとに呼び出します。ステータス：
waiting/processing/pending→ ポーリングを続行completed→ レスポンスからvideo_urlを取得して続行failed→ 停止し、failure_messageをユーザーに表示
待機時間の上限は約10分に設定します。まだ処理中の場合はユーザーに伝え、判断を仰ぎます。
ポーリングループのzshの癖 — 変数名 status はzshで読み取り専用です。ポーリングループ内で status=$(…) と書くと、スクリプトは read-only variable: status でクラッシュします。別の名前（vstate、phase、ready）を使用してください。
6. MP4をダウンロードする
uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py "<video_url>" "<output_path>"
HeyGenが返したURLへのプレーンなHTTPSダウンロードです——動画を作成または変更するためのAPI呼び出しではありません。
7. 結果を報告する
1つの短い返信で次の3つのことをユーザーに伝えます：
- MP4の出力パス
- 使用されたアバタールック
- 結果の長さとファイルサイズ
例
ユーザー：tạo video heygen từ mp3 workspace/audio/episode-3.mp3
あなた：
- 認証チェック → HeyGenツールが存在する場合はスキップ、そうでなければ
mcp__heygen__authenticate+ OAuthフロー完了。 check_duration.py workspace/audio/episode-3.mp3→OK 87.4HEYGEN_AVATAR_LOOKSからランダム選択（例：66e75e22e6584bbdaa56a19088286dc8）。その旨伝える。upload_asset.py workspace/audio/episode-3.mp3→OK 36922ca92326480f8dbb0f57fae1a144mcp__heygen__create_video_from_avatar(avatarId=…, audioAssetId=…, aspectRatio="9:16", resolution="720p", title="episode-3-…")→video_id: 874793a8…mcp__heygen__get_videoを約15秒ごとにポーリング、completedまで →video_urlを取得download_video.py <url> workspace/heygen-clips/episode-3/episode-3_20260510-143022.mp4- パス、ルックID、長さを報告。
このスキルが意図的に行わないこと
- SRTの書き込み/文字起こしは行いません（それは
mkt-ai-video-extract-srt-segmentです）。 - ビジュアル、Bロール、セグメントの計画は行いません（それは
mkt-plan-short-video-edit-16-9です）。 - MP3のチャンク分割は行いません（それは
heygen-short-videoでsplit_audio.pyを使用します）。 - RemotionやHyperFramesとの合成は行いません（それは親オーケストレーターです）。
ユーザーが上記のいずれかを希望する場合は、このスキルを拡張する代わりに、適切なスキルを案内してください。
障害モードとメッセージ
| 症状 | ユーザーに伝える内容 |
|---|---|
| MP3ファイルが見つからない | MP3 không tìm thấy ở <path>. Kiểm tra lại đường dẫn.（でMP3が見つかりません。パスを確認してください。） |
| MP3が300秒を超える | MP3 dài <X>s, vượt giới hạn 5 phút của HeyGen. Dùng skill heygen-short-video (có chunking) thay thế.（MP3の長さが秒で、HeyGenの5分制限を超えています。代わりにheygen-short-videoスキル（チャンク分割あり）を使用してください。） |
| HeyGen MCPが認証されていない | mcp__heygen__authenticate URLを表示し、ユーザーに認証を求め、その後 mcp__heygen__complete_authentication を呼び出す。 |
HEYGEN_API_KEY が見つからない/プレースホルダー | Không tìm thấy HEYGEN_API_KEY. Helper đã thử .env.local, .env, và ~/Documents/GitHub/hoang-ai-marketing/.env. Bạn cần thêm key thật (không phải stub your_*) vào 1 trong các file đó.（HEYGEN_API_KEYが見つかりません。ヘルパーは.env.local、.env、~/Documents/GitHub/hoang-ai-marketing/.envを試しました。これらのファイルのいずれかに実際のキー（スタブyour_*ではありません）を追加する必要があります。） |
HEYGEN_AVATAR_LOOKS がプレースホルダー（avatar_look_id_1,…） | APIキーと同じフォールバック——マーケティングリポジトリから読み取るか、ユーザーに実際のアバターIDを入力するよう求める。 |
| HeyGenが失敗を返す | HeyGen render failed: <failure_message>. Có thể avatar look bị xoá hoặc audio asset không hợp lệ.（HeyGenレンダリング失敗：<failure_message>。アバタールックが削除されたか、オーディオアセットが無効である可能性があります。） |
| クレジット不足 | HeyGenからのエラーを表示——このサーバーバージョンでは get_remaining_credits MCPは公開されていません。ユーザーを https://app.heygen.com/billing に誘導します。 |
ツール名が見つからない（upload_asset / generate_avatar_video / get_avatar_video_status） | 古いMCP名——RESTアップロード + create_video_from_avatar + get_video に置き換えられました。まだ古い名前を使用している呼び出し元を更新してください。 |