how-tos

HeyGen Avatar 6 API 가이드: cURL과 Python으로 만드는 첫 토킹 영상

Poyo.ai Team
7 min read
Share:

HeyGen Avatar 6 API 가이드: cURL과 Python으로 만드는 첫 토킹 영상

이 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자
voicetext를 사용하는 공개 아바타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 상태만 확인해서는 충분하지 않습니다.

본문 codeerror.type대응
400validation_error 등입력 수정: 2~60초를 벗어난 오디오, 알 수 없는 아바타 이름, 다른 모드의 필드. 그대로 재시도하지 않기
401authentication_errorAuthorization: Bearer 헤더 확인
402insufficient_credits_error충전하거나, 실행 중인 텍스트 작업이 정산될 때까지 대기(아래 참고)
429rate_limit_error간격을 두고 재시도
500 / 502 / 503internal_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).

모델1080p2K
heygen-avatar-6-turbo10크레딧($0.05) / 초18크레딧($0.09) / 초
heygen-avatar-620크레딧($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를 자체 스토리지에 다운로드하세요.

Share: