HeyGen MP3 → MP4 (單一用途)
接收一個 MP3 口白，產出一個 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 列舉） | 預設 9:16（TikTok / Reels）。僅當上層協調器覆蓋時才使用 16:9 |
| 解析度（MCP 列舉） | 預設 720p（9:16 時產生 720×1280，16:9 時產生 1280×720） |
對於 MP3 嘴型同步，語音類型為 audio，並提供 audioAssetId——不傳送 voiceId。上述的語音 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，非零 = 停止。
如果 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)，則視為缺失，並回退到行銷 repo 的 .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_*）會自動跳過。
擷取輸出在 stdout 上的 asset_id。
4. 產生虛擬人物影片（MCP）
使用新的 schema 呼叫 mcp__heygen__create_video_from_avatar（舊的 dimension: {width, height} 格式已消失——該工具現在接受 aspectRatio 列舉 + resolution 列舉）：
avatarId: <從允許清單中選取>
audioAssetId: <來自步驟 3>
aspectRatio: "9:16" # 或 "16:9" 當上層覆蓋時
resolution: "720p" # 720p · 1080p · 4k
title: "<mp3-stem>-<timestamp>"
擷取回傳的 video_id（初始狀態將是 waiting）。
為何是音訊（而非文字）： 從現有的 MP3 進行嘴型同步需要 HeyGen 直接消費音訊。在此處傳送 script + voiceId 會讓 HeyGen 切換到 TTS 模式，並完全忽略已上傳的 MP3。
5. 輪詢直到完成
每隔約 10–15 秒使用 video_id 呼叫 mcp__heygen__get_video。狀態：
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>"
純 HTTPS 下載 HeyGen 回傳的 URL——不是用於建立或修改影片的 API 呼叫。
7. 回報結果
在一則簡短回覆中告知使用者三件事：
- 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.4- 從
HEYGEN_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…- 每隔約 15 秒輪詢
mcp__heygen__get_video直到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-roll、分段（這是
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 金鑰相同的回退方式——從行銷 repo 讀取，或要求使用者填入真實的虛擬人物 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 取代。更新任何仍在使用舊名稱的呼叫者。 |