아바타 비디오
아바타, 음성, 대본, 장면 및 배경을 완벽하게 제어하여 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 도구는 인증 및 요청 형식을 자동으로 처리합니다.
| 작업 | 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 참조 - 완료 대기 — 상태가
completed가 될 때까지GET /v2/videos/{video_id}를 폴링합니다. 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 스킬을 대신 사용하세요.
| 사용자 요청 | 비디오 생성 스킬 | 이 스킬 |
|---|---|---|
| "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가 존재하는지 확인합니다.