비디오 생성
텍스트 프롬프트로 완성된 비디오를 생성합니다. 원하는 내용을 설명하면 AI가 스크립트 작성, 아바타 선택, 비주얼, 나레이션, 템포, 자막을 자동으로 처리합니다.
인증
모든 요청에는 X-Api-Key 헤더가 필요합니다. HEYGEN_API_KEY 환경 변수를 설정하세요.
curl -X POST "https://api.heygen.com/v1/video_agent/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "60초 제품 데모 비디오를 만들어 줘."}'
도구 선택
HeyGen MCP 도구(mcp__heygen__*)가 사용 가능하면 직접 HTTP API 호출보다 우선 사용하세요. MCP 도구가 인증과 요청 형식을 자동으로 처리합니다.
| 작업 | MCP 도구 | 대체 (직접 API) |
|---|---|---|
| 프롬프트로 비디오 생성 | mcp__heygen__generate_video_agent | POST /v1/video_agent/generate |
| 비디오 상태 확인 / 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} |
HeyGen MCP 도구가 없으면 참조 파일에 문서화된 대로 직접 HTTP API 호출을 사용하세요.
기본 워크플로우
항상 prompt-optimizer.md 가이드라인을 사용하여 장면, 시간, 비주얼 스타일이 포함된 프롬프트를 구조화하세요.
MCP 도구 사용 시:
- prompt-optimizer.md → visual-styles.md를 사용하여 최적화된 프롬프트 작성
- 프롬프트와 설정(
duration_sec,orientation,avatar_id)과 함께mcp__heygen__generate_video_agent호출 - 반환된
video_id로mcp__heygen__get_video를 호출하여 상태를 폴링하고 다운로드 URL 가져오기
MCP 도구 없음 (직접 API):
- prompt-optimizer.md → visual-styles.md를 사용하여 최적화된 프롬프트 작성
POST /v1/video_agent/generate— 자세한 내용은 video-agent.md 참고GET /v2/videos/<id>— 자세한 내용은 video-status.md 참고
빠른 참조
| 작업 | MCP 도구 | 참고 자료 |
|---|---|---|
| 프롬프트로 비디오 생성 | mcp__heygen__generate_video_agent | prompt-optimizer.md → visual-styles.md → video-agent.md |
| 비디오 상태 확인 / 다운로드 URL 가져오기 | mcp__heygen__get_video | video-status.md |
| 참조 파일 업로드 | — | assets.md |
이 스킬을 사용해야 하는 경우 vs 아바타 비디오
이 스킬은 프롬프트 기반 비디오 생성을 위한 것입니다. 원하는 내용을 설명하면 AI가 나머지를 처리합니다.
사용자가 특정 아바타, 정확한 스크립트, 장면별 음성/배경 구성 또는 다중 장면 구성에 대한 정밀한 제어가 필요하면 아바타 비디오 스킬을 대신 사용하세요.
| 사용자 요청 | 이 스킬 | 아바타 비디오 스킬 |
|---|---|---|
| "X에 대한 동영상 만들어 줘" | ✓ | |
| "제품 데모 영상 만들어 줘" | ✓ | |
| "아바타 Y가 Z라고 정확히 말하게 해 줘" | ✓ | |
| "배경이 다른 여러 장면 비디오" | ✓ | |
| "합성용 투명 WebM" | ✓ |
참조 파일
핵심 워크플로우
- references/prompt-optimizer.md - 효과적인 프롬프트 작성 (핵심 워크플로우 + 규칙)
- references/visual-styles.md - 20가지 명명된 비주얼 스타일 (전체 사양 포함)
- references/prompt-examples.md - 전체 프로덕션 프롬프트 예제 + 바로 사용 가능한 템플릿
- references/video-agent.md - Video Agent API 엔드포인트 세부 정보
기본
- references/video-status.md - 폴링 패턴 및 다운로드 URL
- references/webhooks.md - 웹훅 엔드포인트 및 이벤트
- references/assets.md - 이미지, 비디오, 오디오 참조 파일 업로드
- references/dimensions.md - 해상도 및 종횡비
- references/quota.md - 크레딧 시스템 및 사용량 제한
모범 사례
- 프롬프트 최적화 — 결과물의 차이는 프롬프트 품질에 달려 있습니다. 항상 프롬프트 옵티마이저를 사용하세요.
- 길이 지정 — 예측 가능한 길이를 위해
config.duration_sec을 사용하세요. - 필요시 아바타 고정 — 비디오 간 일관성을 위해
config.avatar_id를 사용하세요. - 참조 파일 업로드 — 에이전트가 브랜드/제품을 이해하도록 도와주세요.
- 프롬프트 반복 개선 — 결과에 따라 개선하세요. Video Agent는 빠른 반복에 적합합니다.