비디오 생성은(는) 무엇을 하나요?
텍스트 프롬프트로 완전한 비디오를 생성합니다. 원하는 내용을 설명하면 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 도구는 인증과 요청 포맷을 자동으로 처리합니다.
| 작업 | 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가 나머지를 처리합니다.
사용자가 특정 아바타, 정확한 스크립트, 장면별 음성/배경 설정, 또는 다중 장면 구성을 세밀하게 제어해야 하는 경우 아바타 비디오(avatar-video) 스킬을 대신 사용하세요.
| 사용자 발화 | 이 스킬 | 아바타 비디오 스킬 |
|---|---|---|
| "X에 대한 비디오 만들어 줘" | ✓ | |
| "제품 데모 만들어 줘" | ✓ | |
| "아바타 Y가 Z라고 정확히 말하게 해줘" | ✓ | |
| "배경이 다른 다중 장면 비디오" | ✓ | |
| "합성용 투명 WebM" | ✓ |
참조 파일
핵심 워크플로우
- references/prompt-optimizer.md - 효과적인 프롬프트 작성법 (핵심 워크플로우 + 규칙)
- references/visual-styles.md - 전체 사양이 포함된 20가지 명명된 시각 스타일
- references/prompt-examples.md - 전체 프로덕션 프롬프트 예제 + 즉시 사용 가능한 템플릿
- references/video-agent.md - 비디오 에이전트 API 엔드포인트 세부 정보
기초
- references/video-status.md - 폴링 패턴 및 다운로드 URL
- references/webhooks.md - 웹훅 엔드포인트 및 이벤트
- references/assets.md - 이미지, 비디오, 오디오를 참조 파일로 업로드
- references/dimensions.md - 해상도 및 화면 비율
- references/quota.md - 크레딧 시스템 및 사용량 제한
모범 사례
- 프롬프트 최적화 — 평범한 결과와 전문적인 결과의 차이는 전적으로 프롬프트 품질에 달려 있습니다. 항상 프롬프트 최적화 도구를 사용하세요.
- 재생 시간 지정 — 예측 가능한 길이를 위해
config.duration_sec을 사용하세요. - 필요시 아바타 고정 — 비디오 간 일관성을 위해
config.avatar_id를 사용하세요. - 참조 파일 업로드 — 에이전트가 브랜드/제품을 이해하도록 도와주세요.
- 프롬프트 반복 개선 — 결과를 보고 개선하세요. 비디오 에이전트는 빠른 반복에 최적입니다.