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로 비디오 생성, 폴링 및 다운로드를 진행합니다.
하드 제약 조건
| 제약 조건 | 허용 값 |
|---|---|
| 자산 업로드 | scripts/upload_asset.py를 통한 REST POST https://upload.heygen.com/v1/asset (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, 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_*)은 자동으로 건너뜁니다.
stdout에 출력된 asset_id를 캡처합니다.
4. 아바타 비디오 생성 (MCP)
새 스키마로 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>-<타임스탬프>"
반환된 video_id를 캡처합니다 (상태는 처음에 waiting).
오디오 사용 이유 (텍스트 아님): 기존 MP3에서 립싱크하려면 HeyGen이 오디오를 직접 소비해야 합니다. 여기서 script + voiceId를 보내면 HeyGen이 TTS 모드로 전환되어 업로드된 MP3를 완전히 무시합니다.
5. 완료될 때까지 폴링
약 10~15초마다 mcp__heygen__get_video를 video_id와 함께 호출합니다. 상태:
waiting/processing/pending→ 계속 폴링completed→ 응답에서video_url을 가져와 진행failed→ 중단,failure_message를 사용자에게 표시
대기 시간은 약 10분으로 제한합니다. 여전히 처리 중이면 사용자에게 알리고 결정을 맡깁니다.
폴링 루프의 zsh 문제 — zsh에서 변수 이름 status는 읽기 전용입니다. 폴링 루프에서 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. 결과 보고
짧은 응답으로 사용자에게 세 가지를 알립니다:
- 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 파일 없음 | Không tìm thấy MP3 tại <path>. Vui lòng kiểm tra lại đường dẫn. (베트남어: "<경로>에 MP3가 없습니다. 경로를 다시 확인하세요.") |
| MP3 > 300초 | MP3 dài <X>s, vượt quá giới hạn 5 phút của HeyGen. Vui lòng 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 một 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로 대체됨. 이전 이름을 사용하는 호출자를 업데이트하세요. |