아바타 비디오
아바타, 음성, 대본, 장면, 배경을 완전히 제어하여 AI 아바타 비디오를 만듭니다. HeyGen의 /v2/video/generate API를 사용하여 단일 또는 다중 장면 비디오를 정확하게 구성합니다.
인증
모든 요청에는 X-Api-Key 헤더가 필요합니다. HEYGEN_API_KEY 환경 변수를 설정하세요.
curl -X GET "https://api.heygen.com/v2/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY"
도구 선택
HeyGen MCP 도구(mcp__heygen__*)를 사용할 수 있다면 직접 HTTP API 호출보다 이것을 우선 사용하세요. 인증과 요청 포맷을 자동으로 처리합니다.
| 작업 | MCP 도구 | 대체 방법 (직접 API) |
|---|---|---|
| 비디오 상태 확인 / URL 가져오기 | mcp__heygen__get_video | GET /v2/videos/{video_id} |
| 계정 비디오 목록 보기 | mcp__heygen__list_videos | GET /v2/videos |
| 비디오 삭제 | mcp__heygen__delete_video | DELETE /v2/videos/{video_id} |
비디오 생성(POST /v2/video/generate) 및 아바타/음성 목록 조회는 직접 API 호출로 수행됩니다. 아래 참조 파일을 참고하세요.
기본 워크플로우
- 아바타 목록 보기 —
GET /v2/avatars→ 아바타를 선택하고 미리보기한 후avatar_id와default_voice_id를 기록합니다. avatars.md 참조 - 음성 목록 보기 (필요한 경우) —
GET /v2/voices→ 아바타의 성별/언어와 일치하는 음성을 선택합니다. voices.md 참조 - 대본 작성하기 — 각 장면을 하나의 개념으로 구성합니다. scripts.md 참조
- 비디오 생성하기 —
POST /v2/video/generate에 아바타, 음성, 대본, 장면별 배경을 포함합니다. video-generation.md 참조 - 완료 확인하기 —
GET /v2/videos/{video_id}로 상태가completed가 될 때까지 폴링합니다. video-status.md 참조
빠른 참조
| 작업 | 참고 문서 |
|---|---|
| 아바타 목록 및 미리보기 | avatars.md |
| 음성 목록 및 선택 | voices.md |
| 대본 작성 및 구조화 | scripts.md |
| 비디오 생성 (단일 또는 다중 장면) | video-generation.md |
| 사용자 정의 배경 추가 | backgrounds.md |
| 캡션/자막 추가 | captions.md |
| 텍스트 오버레이 추가 | text-overlays.md |
| 투명 WebM 비디오 생성 | video-generation.md (WebM 섹션) |
| 템플릿 사용 | templates.md |
| 사진으로 아바타 생성 | photo-avatars.md |
| 비디오 상태 확인 / 다운로드 | video-status.md |
| 자산 업로드 (이미지, 오디오) | assets.md |
| Remotion과 함께 사용 | remotion-integration.md |
| 웹훅 설정 | webhooks.md |
이 스킬을 사용해야 하는 경우 vs 비디오 생성 스킬
이 스킬은 정밀한 제어를 위한 것입니다. 아바타를 직접 선택하고, 정확한 대본을 작성하며, 각 장면을 구성합니다.
사용자가 단순히 비디오 아이디어를 설명하고 나머지 (대본, 아바타, 시각 자료)를 AI가 처리하도록 하려면 대신 create-video 스킬을 사용하세요.
| 사용자 요청 | Create Video 스킬 | 이 스킬 |
|---|---|---|
| "X에 관한 비디오를 만들어 줘" | ✓ | |
| "제품 데모를 만들어 줘" | ✓ | |
| "아바타 Y가 정확히 Z라고 말하게 해 줘" | ✓ | |
| "배경이 다른 다중 장면 비디오" | ✓ | |
| "합성용 투명 WebM" | ✓ | |
| "내 대본에 이 특정 음성을 사용해 줘" | ✓ | |
| "정확한 사양으로 비디오를 일괄 생성해 줘" | ✓ |
참조 파일
핵심 비디오 생성
- references/avatars.md - 아바타 목록, 스타일, avatar_id 선택
- references/voices.md - 음성 목록, 로케일, 속도/음높이
- references/scripts.md - 대본 작성, 일시 정지, 속도 조절
- references/video-generation.md - POST /v2/video/generate 및 다중 장면 비디오
비디오 사용자 정의
- references/backgrounds.md - 단색, 이미지, 비디오 배경
- references/text-overlays.md - 글꼴 및 위치 지정으로 텍스트 추가
- references/captions.md - 자동 생성 캡션 및 자막
고급 기능
- references/templates.md - 템플릿 목록 및 변수 대체
- references/photo-avatars.md - 사진으로 아바타 생성
- references/webhooks.md - 웹훅 엔드포인트 및 이벤트
통합
- references/remotion-integration.md - Remotion 구성에서 HeyGen 사용
기초
- references/video-status.md - 폴링 패턴 및 다운로드 URL
- references/assets.md - 이미지, 비디오, 오디오 업로드
- references/dimensions.md - 해상도 및 종횡비
- references/quota.md - 크레딧 시스템 및 사용량 제한
모범 사례
- 비디오 생성 전에 아바타 미리보기 —
preview_image_url을 다운로드하여 사용자가 확정하기 전에 아바타를 볼 수 있게 하세요. - 아바타의 기본 음성 사용 — 대부분의 아바타에는 자연스러운 결과를 위해 미리 매칭된
default_voice_id가 있습니다. - 대체 방법: 수동으로 성별 일치 — 기본 음성이 없는 경우 아바타와 음성의 성별이 일치하는지 확인하세요.
- 개발 시 테스트 모드 사용 —
test: true를 설정하여 크레딧이 소모되지 않도록 하세요. (출력물에는 워터마크가 표시됩니다.) - 여유 있는 타임아웃 설정 — 비디오 생성은 종종 5-15분, 때로는 더 오래 걸립니다.
- 입력값 검증 — 생성 전에 아바타 및 음성 ID가 존재하는지 확인하세요.