아바타 비디오
HeyGen의 /v2/video/generate API를 사용하여 아바타, 음성, 스크립트, 장면, 배경을 완벽하게 제어하는 AI 아바타 비디오를 만듭니다. 단일 장면 또는 여러 장면 비디오를 정확한 구성으로 제작할 수 있습니다.
인증
모든 요청에 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 도구는 인증과 요청 형식을 자동으로 처리합니다.
| 작업 | 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 Create Video 스킬
이 스킬은 정밀한 제어가 필요할 때 사용합니다. 즉, 사용자가 아바타를 직접 선택하고, 정확한 스크립트를 작성하며, 각 장면을 구성할 수 있습니다.
사용자가 단순히 비디오 아이디어를 설명하고 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가 존재하는지 확인합니다.