비디오 생성은(는) 무엇을 하나요?
텍스트 프롬프트로 완전한 비디오를 생성합니다. 원하는 내용을 설명하면 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 도구 | 대체 (직접 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 를 사용하여 최적화된 프롬프트 작성
mcp__heygen__generate_video_agent호출 (프롬프트 및 설정: duration_sec, orientation, avatar_id)- 반환된 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 - 비디오 에이전트 API 엔드포인트 세부 정보
기본
- references/video-status.md - 폴링 패턴 및 다운로드 URL
- references/webhooks.md - 웹훅 엔드포인트 및 이벤트
- references/assets.md - 이미지, 비디오, 오디오를 참조로 업로드
- references/dimensions.md - 해상도 및 종횡비
- references/quota.md - 크레딧 시스템 및 사용량 제한
모범 사례
- 프롬프트 최적화 — 평범한 결과와 전문적인 결과의 차이는 전적으로 프롬프트 품질에 달려 있습니다. 항상 프롬프트 최적화 도구를 사용하세요.
- 길이 지정 — 예측 가능한 길이를 위해
config.duration_sec을 사용하세요. - 필요시 아바타 고정 — 비디오 간 일관성을 위해
config.avatar_id를 사용하세요. - 참조 파일 업로드 — 에이전트가 브랜드/제품을 이해하도록 도와주세요.
- 프롬프트 반복 개선 — 결과를 바탕으로 개선하세요. 비디오 에이전트는 빠른 반복에 적합합니다.