![]()
이 HeyGen Avatar 6 API 가이드는 API 키 발급부터 PoYo에서 토킹 영상을 완성하기까지의 과정을 안내합니다. 모델 ID heygen-avatar-6(또는 heygen-avatar-6-turbo)로 JSON 요청 하나를 제출하고, 반환된 작업 ID를 보관한 뒤 MP4가 준비될 때까지 폴링합니다. 아래의 모든 요청 본문은 PoYo 문서 형식을 따릅니다. 입력을 먼저 확인하고 싶다면 HeyGen Avatar 6 모델 페이지의 Playground를 이용하세요.
시작하기 전에
poyo.ai/dashboard/api-key에서 키를 만들고POYO_API_KEY로 export하세요. 키는 서버에만 두세요.- 모든 입력 파일을 공개적으로 직접 다운로드할 수 있는 HTTP 또는 HTTPS URL에 호스팅하세요. PoYo가 미디어를 직접 가져오므로 요청 안의 업로드는 받지 않습니다.
- 티어를 고르세요. 두 ID는 같은 필드를 받습니다. Turbo는 1080p에서 초당 10크레딧($0.05), Avatar 6은 20크레딧($0.10)입니다. Avatar 6 vs Turbo를 참고하세요.
cURL로 보내는 첫 HeyGen Avatar 6 API 요청
가장 빠른 첫 요청에는 미디어가 전혀 필요 없습니다. HeyGen 공개 아바타가 텍스트를 읽어 줍니다.
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'
성공한 응답에는 "code": 200과 data.task_id가 있고, status는 not_started입니다. 이는 대기열에 들어간 작업이지 영상이 아닙니다. 폴링하세요.
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
상태는 not_started, running, finished, failed입니다. finished가 되면 MP4는 file_type이 video인 data.files[]에 있고, data.credits_amount에 과금액이 표시됩니다. failed라면 data.error_message를 확인하세요.
상한이 있는 Python 폴링 루프
2026년 11월 19일 출시 당일 테스트에서 짧은 텍스트 클립은 제출부터 결과까지 약 22.4분이 걸렸습니다. 이 루프는 5초마다 폴링하고(상태 문서는 25초 권장), 15분에서 멈추며, 타임아웃 시 절대 재제출하지 않습니다. 두 번째 제출은 두 번째 과금 작업이 되기 때문입니다.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
response.raise_for_status()
body = response.json()
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(f"{body.get('code')} {err.get('type')}: {err.get('message')}")
return body["data"]
def generate(payload, timeout_s=900):
task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
task_id = task["task_id"]
print("task", task_id, flush=True)
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
videos = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "video"]
return videos[0], task.get("credits_amount")
raise TimeoutError("still running; poll this task again later: " + task_id)
url, credits = generate({
"model": "heygen-avatar-6",
"input": {
"image_urls": ["https://example.com/presenter.png"],
"audio_url": "https://example.com/speech.mp3",
"prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
"resolution": "1080p",
},
})
print(url, credits)
프로덕션에서는 폴링 대신 최상위 callback_url을 추가하세요. 작업이 finished 또는 failed가 되면 PoYo가 같은 작업 객체(code / data 래퍼 없이)를 X-Webhook-Signature에 HMAC-SHA256 서명과 함께 POST합니다. 서명 규칙은 웹훅 문서에 있습니다.
HeyGen Avatar 6 API의 세 가지 입력 모드
모드 전환 스위치는 없습니다. avatar가 있으면 공개 아바타 모드, 그렇지 않고 video_url이 있으면 참조 영상 모드, 둘 다 없으면 사진 모드로 실행됩니다. 요청 하나에는 한 모드의 입력만 사용하세요.
텍스트를 사용하는 공개 아바타 모드
위에서 본 그대로입니다. avatar는 1,248개 공개 룩 중 하나, text는 최대 1,000자, voice는 102개 보이스 중 하나(기본값 Warm Pro Narrator)입니다. 카탈로그에서 룩과 보이스를 고르는 방법은 텍스트 투 아바타 안내에서 다룹니다.
내 오디오를 사용하는 공개 아바타 모드
text와 voice를 audio_url로 바꾸세요. aspect_ratio는 그대로 적용됩니다.
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
사진 모드
실제 인물 사진 한 장과 음성입니다. 영상은 사진의 화면 비율을 유지하므로, 보내기 전에 원하는 프레임으로 사진을 잘라 두세요. callback_url은 input 안이 아니라 model과 같은 수준에 둡니다.
{
"model": "heygen-avatar-6",
"callback_url": "https://your-domain.com/callback",
"input": {
"image_urls": ["https://example.com/presenter.png"],
"audio_url": "https://example.com/speech.mp3",
"prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
"resolution": "1080p"
}
}
참조 영상 모드
애니메이션이나 일러스트 캐릭터용입니다. video_url은 캐릭터 클립이며, image_urls로 같은 캐릭터의 정지 이미지 한 장을 선택적으로 추가할 수 있습니다. 출력은 클립의 화면 비율을 유지합니다.
{
"model": "heygen-avatar-6-turbo",
"input": {
"video_url": "https://example.com/cartoon-character.mp4",
"image_urls": ["https://example.com/cartoon-character.png"],
"audio_url": "https://example.com/speech.mp3",
"resolution": "2K"
}
}
HeyGen Avatar 6 API 필드 검증 규칙
제출하기 전에 자체 코드에서 확인하세요. 문서에 명시된 제한입니다.
| 필드 | 모드 | 규칙 |
|---|---|---|
model | 전체 | heygen-avatar-6 또는 heygen-avatar-6-turbo |
image_urls | 사진(필수), 참조 영상(선택) | 정확히 URL 1개의 배열 |
video_url | 참조 영상 | 최소 2초, 최대 50 MB |
avatar | 공개 아바타 | 목록의 1,248개 이름 중 하나 |
audio_url | 사진, 참조 영상, 또는 공개 아바타에서 text 대신 | 2~60초, 최대 15 MB |
text | 공개 아바타 | 1~1,000자 |
voice | text를 사용하는 공개 아바타 | 102개 이름 중 하나 |
prompt | 전체 | 최대 1,200자 |
aspect_ratio | 공개 아바타 | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | 전체 | 1080p(기본값) 또는 2K |
아바타와 보이스 이름은 대소문자와 여분의 공백과 관계없이 일치하지만, 문서에 명시된 예외가 하나 있습니다. Hope와 Hope (끝에 공백)는 서로 다른 보이스입니다. 입력 스키마는 추가 필드를 허용하지 않으므로 HeyGen 자체 API의 motion_expressiveness나 motion_prompt 같은 HeyGen 네이티브 옵션은 보내지 마세요. PoYo에서는 동작 지시를 prompt에 넣습니다.
처리해야 할 오류
응답 본문의 code를 항상 확인하세요. 일부 검증 오류는 HTTP 200에 "code": 400으로 돌아오므로 HTTP 상태만 확인해서는 충분하지 않습니다.
본문 code | error.type | 대응 |
|---|---|---|
| 400 | validation_error 등 | 입력 수정: 2~60초를 벗어난 오디오, 알 수 없는 아바타 이름, 다른 모드의 필드. 그대로 재시도하지 않기 |
| 401 | authentication_error | Authorization: Bearer 헤더 확인 |
| 402 | insufficient_credits_error | 충전하거나, 실행 중인 텍스트 작업이 정산될 때까지 대기(아래 참고) |
| 429 | rate_limit_error | 간격을 두고 재시도 |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | 지수 백오프로 재시도 |
오디오 길이, 참조 영상 길이, 아바타 이름은 제출 시점에 검사되므로, 이런 실수는 몇 분 뒤의 작업 실패가 아니라 즉시 400으로 드러납니다.
402에는 HeyGen 특유의 함정이 있습니다. 출시 당일 테스트에서 텍스트 작업 두 개를 제출한 뒤, 세 번째 요청(Turbo, 2K, 22단어)이 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."였습니다. 텍스트 작업은 실행 중에 크레딧을 잡아 두므로, 최종 요금이 잔액 안에 들어오더라도 텍스트를 연달아 제출하면 402가 날 수 있습니다. 텍스트 작업을 대기열에 넣거나, 오류 메시지에 이미 두 숫자가 모두 들어 있으니 이를 사용자에게 보여 주세요.
첫 HeyGen Avatar 6 API 청구액 계산 방식
PoYo는 출력 초 단위로 과금하며 정수 초로 올림합니다(1크레딧 = $0.005).
| 모델 | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10크레딧($0.05) / 초 | 18크레딧($0.09) / 초 |
heygen-avatar-6 | 20크레딧($0.10) / 초 | 29크레딧($0.145) / 초 |
audio_url사용 시(모든 모드): 요금은 오디오 길이를 올림한 값이며 제출 시 차감됩니다. 1080p Avatar 6에서 12.3초 클립은 13 × 20 = 260크레딧($1.30)입니다.text사용 시: 제출 시 크레딧이 예약되고 작업이 끝나면 완성된 영상 길이로 정산됩니다. 테스트에서 Turbo의 27단어 스크립트는 10.16초가 나와 11초로 과금되며 현재 요금으로 110크레딧(11초 × 10, $0.55)이고, Avatar 6의 21단어 스크립트는 6.88초가 나와 7초로 과금되며 현재 요금으로 140크레딧(7초 × 20, $0.70)입니다.
대조할 숫자는 완료된 작업의 data.credits_amount입니다. 더 많은 예시는 HeyGen Avatar 6 API 가격에 있습니다.
자주 묻는 질문
Python에서 HeyGen Avatar 6 API를 호출하려면?
requests로 https://api.poyo.ai/api/generate/submit에 JSON을 POST한 뒤, 위의 루프처럼 기한을 두고 /api/generate/status/{task_id}를 폴링하세요. 어떤 HTTP 클라이언트든 작동하며 SDK는 필수가 아닙니다.
HeyGen Avatar 6 API에 콜백이 있나요?
네. 요청의 최상위에 callback_url을 추가하세요. 작업이 완료되거나 실패하면 PoYo가 작업 데이터를 POST합니다.
HeyGen Avatar 6 API 요청이 HTTP 200을 반환했는데 작업이 없는 이유는?
본문을 확인하세요. code가 200이 아니면 HTTP 200이라도 요청은 실패한 것이며, 이유는 error.message에 있습니다.
HeyGen Avatar 6 API에 파일을 직접 업로드할 수 있나요?
아니요. image_urls, video_url, audio_url은 PoYo가 다운로드하는 공개 HTTP 또는 HTTPS URL을 받습니다.
HeyGen Avatar 6 API 결과는 얼마나 보관되나요?
생성된 영상은 생성 후 3일간 접근할 수 있습니다. MP4를 자체 스토리지에 다운로드하세요.