![]()
HeyGen Avatar 6 API는 스크립트만으로 프레젠터 영상을 만들 수 있습니다. 공개 아바타 모드에서 HeyGen의 스톡 룩 1,248개 중 하나를 지정하고, 최대 1,000자의 text를 보내고, 보이스 102개 중 하나를 고르면 heygen-avatar-6(또는 heygen-avatar-6-turbo)이 립싱크된 MP4를 반환합니다. 사진도, 녹음도, 내 쪽의 텍스트 음성 변환 단계도 필요 없습니다. 이 안내에서는 카탈로그에서 룩과 보이스를 고르는 법, prompt로 제스처를 지시하는 법, 프레임 모양을 고르는 법, 텍스트 요청의 비용을 다룹니다. HeyGen Avatar 6 모델 페이지에서도 룩을 둘러볼 수 있습니다.
텍스트 투 아바타 요청
다음은 텍스트를 사용하는 공개 아바타 모드의 문서화된 본문입니다.
{
"model": "heygen-avatar-6-turbo",
"input": {
"avatar": "Abigail Office Front",
"text": "Hello and welcome to this demonstration of HeyGen Avatar 6.",
"voice": "Warm Pro Narrator",
"prompt": "Speak with calm confidence and nod slightly at the end.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}
| 필드 | 필수 | 규칙 |
|---|---|---|
avatar | 예 | 룩 이름 1,248개 중 하나 |
text | 예(audio_url 대신) | 1~1,000자 |
voice | 아니요 | 이름 102개 중 하나. 기본값 Warm Pro Narrator |
prompt | 아니요 | 최대 1,200자의 연출 지시 |
aspect_ratio | 아니요 | 16:9(기본값), 9:16, 1:1, 4:5, 5:4 |
resolution | 아니요 | 1080p(기본값) 또는 2K |
이 모드를 선택하는 것은 avatar의 존재입니다. image_urls나 video_url을 함께 보내지 마세요. 요청 하나에는 한 모드의 입력만 사용합니다. POST https://api.poyo.ai/api/generate/submit에 제출하고 HeyGen Avatar 6 API 가이드처럼 /api/generate/status/{task_id}를 폴링하세요.
카탈로그에서 아바타 룩 고르기
PoYo는 모든 이름을 Avatars and Voices 페이지와 JSON 카탈로그로 공개합니다. 카탈로그에는 다섯 개의 키가 있습니다.
| 키 | 내용 |
|---|---|
models | heygen-avatar-6, heygen-avatar-6-turbo(같은 이름이 두 모델에서 작동) |
default_voice | Warm Pro Narrator |
avatars | 룩 이름 1,248개 전체, 평면 목록 |
avatars_by_person | 같은 룩을 156명별로 그룹화 |
voices | 보이스 이름 102개 전체 |
각 인물에게는 하나 이상의 룩이 있고, 각 룩이 별도의 avatar 값입니다. Abigail은 다섯 개(Abigail (Upper Body), Abigail Office Front, Abigail Office Side, Abigail Sofa Front, Abigail Sofa Side), Annie는 54개이며, 8명은 룩이 하나뿐입니다. 이름이 배경, 의상, 카메라 각도를 설명하므로 보통은 미리 보지 않고도 고를 수 있습니다.
| 원하는 것 | 이름에서 찾을 단어 | 예시 |
|---|---|---|
| 카메라를 바라보는 프레젠터 | Front | Abigail Office Front, Bryan Suit Front |
| 4분의 3 각도 | Side | Abigail Office Side |
| 앉아 있는 편안한 분위기 | Sofa, Sitting, Lounge | Annie Sofa Sitting Front |
| 역할이나 배경 | Doctor, Nurse, Yoga, Tech Expert | Ann Doctor Standing, Adriana Nurse Front, Amelia Yoga Front, Bryan Tech Expert |
약 480개 이름에 Front가, 약 430개 이름에 Side가 들어 있습니다. 설명 영상 시리즈라면 한 인물을 골라 그 사람의 Front 룩만 사용해 영상마다 프레젠터가 같게 유지하세요. 컷어웨이에는 짝이 되는 Side 룩을 쓰세요.
이름은 대소문자와 여분의 공백과 관계없이 일치하므로 abigail office front로 Abigail Office Front가 선택됩니다. PoYo는 제출 시 avatar를 목록과 대조하므로, 오타는 작업 실패가 아니라 즉시 400으로 돌아옵니다. 먼저 자체 코드에서 검증하세요.
import requests
catalog = requests.get(
"https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()
def norm(name: str) -> str:
return " ".join(name.split()).lower()
AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])
def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
if norm(avatar) not in AVATARS:
raise ValueError(f"unknown avatar: {avatar!r}")
if not 1 <= len(text) <= 1000:
raise ValueError("text must be 1-1,000 characters")
if voice is not None and voice not in VOICES:
raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
if prompt is not None and len(prompt) > 1200:
raise ValueError("prompt must be at most 1,200 characters")
body = {"avatar": AVATARS[norm(avatar)], "text": text,
"aspect_ratio": aspect_ratio, "resolution": resolution}
if voice:
body["voice"] = voice
if prompt:
body["prompt"] = prompt
return {"model": model, "input": body}
보이스 검사는 의도적으로 정확한 이름을 사용합니다. 이유는 다음 섹션에서 설명합니다.
보이스 고르기
voice는 누가 text를 읽을지 결정합니다. 생략하면 Warm Pro Narrator가 됩니다. 102개 보이스에는 평범한 이름(Andrew, Ivy, Jessica Anne Bogart), 설명적인 이름(Calm Chloe, Professor Dean, Radio Rick, Chill Brian), 이름에 스타일 태그가 붙은 것이 있습니다.
자주 걸리는 세 가지:
- 끝 공백이 중요할 수 있습니다. 문서는
Hope와Hope(끝에 공백)가 서로 다른 보이스라고 명시합니다.Archer,Cassidy,Adam Stone,Spuds Oxley,Andrew Rizz도 카탈로그에서 공백으로 끝납니다. 이름을 다시 입력하지 말고 JSON에서 복사하세요. - 일부 이름에는 이모지나 파일명 같은 접미사가 들어 있습니다. 예를 들어
Cute Chloe - Friendly 😊나Brenda - UGC - 1.mp4입니다. 이 문자들도 이름의 일부입니다. 요청 본문을 UTF-8 JSON으로 보내면 이름이 그대로 전달됩니다. - 보이스는 아바타에 묶여 있지 않습니다. 102개 보이스 중 어떤 것이든 1,248개 룩 중 어떤 것이든 읽게 할 수 있습니다. 화면 속 인물에 어울리는 보이스를 고르세요. 출시 당일 테스트에서는
Bryan Tech Expert에Andrew를,Abigail Office Front에Jessica Anne Bogart를 조합했습니다.
voice는 text를 보낼 때만 적용됩니다. 대신 audio_url을 보내면 아바타가 내 녹음을 말하고 voice는 사용되지 않습니다.
prompt로 제스처 지시하기
prompt는 제스처, 표정, 자세에 대한 최대 1,200자의 연출 지시를 받습니다. HeyGen의 기술 보고서는 이 기법을 "동작을 대사 옆에 적으세요. Avatar 6이 정확한 타이밍에 연기합니다."라고 설명합니다. 예시는 "친절한 약사. 'Hello'에서 엄지를 들어 올린다. 'the counter on the left'에서 검지로 옆을 가리킨다."입니다.
이 형식을 따르는 패턴:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Bryan Tech Expert",
"text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
"voice": "Andrew",
"prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}
프롬프트를 유용하게 만드는 팁:
- 각 동작이 맞춰질
text의 정확한 단어를 인용해 신호가 모호하지 않게 하세요. - 먼저 역할이나 분위기 하나를 적고("Friendly product expert"), 그다음 신호를 적으세요.
- 구체적인 신호가 없을 때는
prompt를 생략하세요. HeyGen의 Avatar 6 출시 페이지에 따르면 모델은 스스로 "제스처, 감정, 표정을 스크립트에 맞춥니다".
게시 위치에 맞는 화면 비율 고르기
aspect_ratio는 공개 아바타 모드에만 있습니다. 사진 모드와 참조 영상 모드는 입력의 형태를 유지합니다.
| 게시 위치 | aspect_ratio |
|---|---|
| 웹사이트, YouTube, LMS 강의 | 16:9(기본값) |
| 쇼츠, 릴스, TikTok, 스토리 | 9:16 |
| 정사각형 피드 게시물, 앱 내 카드 | 1:1 |
| 세로형 피드 게시물 | 4:5 |
| 가로형 피드 게시물 | 5:4 |
resolution은 별개로, 어떤 비율에서든 1080p 또는 2K입니다. 2K는 초당 비용이 더 높으므로 초안은 1080p로 렌더링하세요.
영상 길이와 비용
텍스트를 사용하면 영상은 아바타가 최대 1,000자를 읽는 데 걸리는 만큼의 길이가 됩니다. 과금은 완성된 영상 길이를 정수 초로 올림한 값입니다. 크레딧은 제출 시 예약되고 작업이 끝나면 실제 초로 정산됩니다.
2026년 11월 19일 프로덕션 API에서 실행한 출시 당일 테스트(16:9, 1080p):
| 모델 | 아바타 / 보이스 | 스크립트 | 출력 | 현재 요금 기준 비용 | 소요 시간 |
|---|---|---|---|---|---|
heygen-avatar-6-turbo | Abigail Office Front / Jessica Anne Bogart | 27단어 | 10.16초 | 110크레딧($0.55) | 약 2.4분 |
heygen-avatar-6 | Bryan Tech Expert / Andrew | 21단어 | 6.88초 | 140크레딧($0.70) | 약 2분 |
이 두 실행에서는 초당 약 2.7단어와 3.1단어였습니다. 대략적인 예산 산정에는 유용하지만, 속도는 보이스와 스크립트에 따라 달라지므로 보장은 아닙니다. 초당 요금은 Turbo가 1080p에서 10크레딧($0.05), 2K에서 18($0.09), Avatar 6이 20크레딧($0.10) 또는 29($0.145)입니다. 자세한 내용은 HeyGen Avatar 6 API 가격을 참고하세요.
텍스트 작업은 실행 중에 예약을 잡고 있으므로 한꺼번에 많이 보내면 HTTP 200에 본문 code 402(insufficient_credits_error)가 반환될 수 있습니다. 테스트에서 세 번째 요청이 "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks."라는 메시지로 거부되었습니다. 텍스트 작업을 대기열에 넣거나 진행 중인 예약분을 감당할 잔액을 유지하세요. 반복 작업 중에는 Turbo를 사용하고, 전환 시점은 Avatar 6 vs Turbo 비교에서 확인하세요.
자주 묻는 질문
HeyGen Avatar 6 API로 텍스트를 토킹 아바타 영상으로 만들 수 있나요?
네. 공개 아바타 모드에서 avatar, 최대 1,000자의 text, 선택적으로 voice를 보내세요. 오디오 파일은 필요 없습니다.
HeyGen Avatar 6 API 아바타와 보이스 목록은 어디에 있나요?
PoYo 문서의 Avatars and Voices 페이지와, avatars, avatars_by_person, voices 키가 있는 다운로드 가능한 JSON 카탈로그에 있습니다.
HeyGen Avatar 6 API의 기본 보이스는 무엇인가요?
voice를 생략하면 사용되는 Warm Pro Narrator입니다.
스톡 아바타 대신 내 사진과 텍스트를 쓸 수 있나요?
아니요. text는 공개 아바타 모드에서만 작동합니다. 내 사진을 쓰려면 image_urls와 audio_url을 사용하는 사진 모드를 쓰고, 필요하면 먼저 TTS 모델로 오디오를 생성하세요.
HeyGen Avatar 6 텍스트 투 아바타는 어떤 화면 비율을 지원하나요?
16:9, 9:16, 1:1, 4:5, 5:4이며, 1080p 또는 2K입니다.
HeyGen Avatar 6 API 텍스트 요청은 어떻게 과금되나요?
완성된 영상 길이를 정수 초로 올림해 모델의 초당 요금으로 과금합니다. 크레딧은 제출 시 예약되고 작업이 끝나면 정산됩니다.