블로그

사용 가이드

HiAPI API로 heygen-avatar-iv를 사용해 숏폼 영상을 생성하기: 개발자 가이드

디지털 휴먼과 오디오 입력, 스크립트 리듬, 가로세로 비율과 길이, 배치 생성까지 — 실행 가능한 HiAPI 요청 포함

Nov 18, 2026
커버 이미지: 짙은 커피색 바탕 위에 넓은 오트밀색과 황동색 직조 띠가 교차하여 평평한 바구니 직조 패턴을 이룹니다.
이 페이지에서

숏폼 영상에 heygen-avatar-iv를 선택하는 이유

숏폼 영상은 이제 제품 출시, 버전 업데이트 공지, 문서 설명, 소셜 미디어 숏클립의 기본 배포 채널이 되었습니다. 대부분의 엔지니어링 팀에게 병목은 편집이 아니라, 촬영 스튜디오를 예약하거나 실제 진행자와 소재를 주고받지 않고도 실제 인물이 출연해 말하는 나레이션 소재를 안정적으로 생산하는 일입니다.

바로 이 지점을 디지털 휴먼 영상 생성이 메웁니다. 시각적 외형과 오디오/음성 소스를 제공하면, 모델이 해당 디지털 휴먼이 스크립트를 읽는 렌더링 클립을 반환합니다.heygen-avatar-iv는 HiAPI 카탈로그에서 이 워크플로를 위한 엔드포인트로, 세로 화면 우선의 짧은 클립을 제공하며 진행자가 카메라를 정면으로 응시하고 말합니다.

이 모델은 다음과 같은 상황에 적합합니다:

  • 대량 생산이 필요하다. 같은 공지의 현지화 버전 열 개, 또는 릴리스마다 하나씩 매일 클립을 만드는 것은 한 번의 촬영이 아니라 반복되는 루프입니다.
  • 콘텐츠가 스크립트로 결정된다. 메시지가 글 안에 있다면 디지털 휴먼 진행자로 충분합니다.
  • 재현 가능성을 원한다. 요청 하나가 파일 하나이므로 비교하고, 버전 관리하고, 다시 실행할 수 있습니다. 이는 녹화 세션과 다릅니다.
  • 이미 API를 호출하고 있다. HTTP 호출 한 번이면 기존 파이프라인에 붙일 수 있고, 별도 UI를 가진 새 도구를 도입할 필요가 없습니다.

즉흥적이고 큰 제스처가 많은 연기나, 특정 인물의 물리적 존재 자체가 판매 포인트인 상황에는 맞지 않습니다. heygen-avatar-iv를 렌더러로 생각하세요. 같은 입력이면 같은 종류의 출력이 나와야 하며, 바로 그 점이 스크립트화를 가능하게 합니다.

이 가이드의 나머지 부분은 단일 테스트 호출에서 배치 루프까지, 직접 맞춰 쓸 수 있는 실행 가능한 curl과 Python과 함께 설명합니다. 모델 세부 정보와 파라미터는 heygen-avatar-iv 모델 페이지를 참고하세요.

스크립트와 디지털 휴먼 외형이 직조기 같은 교차점을 통해 하나의 세로 숏폼 영상 프레임으로 합쳐집니다.

heygen-avatar-iv 요청의 구성

생성 코드를 작성하기 전에 요청을 두 개의 독립적인 입력 그룹으로 모델링하세요. 초기 버그의 거의 전부가 이 둘을 혼동하는 데서 비롯됩니다.

첫 번째 그룹: 시각적 외형

이것은 누가 출연하는가입니다. 진행자의 얼굴, 구도, 전체적인 겉모습을 결정하는 디지털 휴먼 선택입니다. 하나의 캠페인에서는 이 그룹을 일정하게 유지하세요. 같은 제품에 대한 다섯 개 클립을 만든다면, 모두 같은 외형 블록을 공유해야 시리즈가 같은 진행자처럼 보입니다.

두 번째 그룹: 오디오와 음성

이것은 무엇을 어떻게 말하는가입니다. 요청에 따라 오디오 소스는 스크립트 텍스트를 읽는 음성 선택일 수도 있고, 제공된 오디오 트랙일 수도 있습니다. 이 그룹은 클립마다 바뀝니다. 새 스크립트, 새 리듬, 때로는 현지화를 위한 새 음성입니다.

호출에 매핑되는 방식

HiAPI 요청은 두 그룹을 하나의 페이로드에 담아 생성 엔드포인트로 보냅니다. 개념적으로는 다음과 같습니다:

request
├── avatar / identity block   → 하나의 시리즈에서 일정하게 유지
└── audio / voice block       → 클립마다 변경
        └── 스크립트 텍스트 또는 오디오 소스

이 분할은 두 가지 실용 규칙으로 이어집니다:

  1. 오디오 그룹은 파라미터화하고, 외형 그룹은 고정한다. 코드에서 외형은 모듈 수준 상수로 두고, 스크립트와 음성은 함수 인자로 전달하세요. 이렇게 하면 구조적으로 한 시리즈의 시각적 일관성이 보장됩니다.
  2. 디버깅할 때는 한 번에 한 그룹만 바꾼다. 클립이 이상하게 보이면 외형만 바꾸고, 소리가 이상하면 오디오 그룹만 바꾸세요. 유료 렌더링 호출에서 두 변수를 동시에 바꾸는 디버깅은 비용이 큽니다.

또한 오디오 그룹이 텍스트 기반인지 오디오 트랙 기반인지 일찍 정하세요. 이 선택이 다음 섹션의 리듬을 결정하기 때문입니다. 제공된 오디오 트랙은 타이밍을 정하고, 생성된 음성은 스크립트를 따릅니다.

정확한 필드 이름, 허용되는 값, 기본값은 모델 페이지에 나열되어 있으니, 한 번 읽고 코드 곳곳에 리터럴을 흩뿌리는 대신 설정 객체에 고정하세요.

두 입력 그룹, 즉 시각적 외형과 오디오/음성 소스가 하나의 생성 호출로 엮입니다.

curl로 첫 호출 실행하기

짧은 클립부터 시작하세요. 이 호출의 목적은 출력 품질이 아니라, 자동화를 하기 전에 자격 증명, 페이로드 형태, 다운로드 경로를 엔드투엔드로 검증하는 것입니다.

키를 환경 변수로 설정해 평문이 셸 기록에 남지 않게 하세요:

export HIAPI_API_KEY="your_key_here"

그런 다음 최소 요청을 보내세요. 자신의 디지털 휴먼 선택과 짧은 한 줄 스크립트로 바꾸세요:

curl -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-iv",
    "input": {
      "avatar": "<avatar_identifier>",
      "script": "디지털 휴먼 파이프라인의 30초 테스트입니다. 화면에서 이 문장을 읽을 수 있다면 요청 형태가 올바릅니다.",
      "voice": "<voice_identifier>",
      "aspect_ratio": "9:16",
      "duration": 30
    }
  }'

순서대로 확인하세요:

  • 인증. 여기서 자격 증명 오류가 나면 멈추세요. 하위의 어떤 것도 중요하지 않습니다.
  • 페이로드 검증. 스키마 오류는 문제 있는 필드를 알려줍니다. 한 번에 필드 하나씩 고치세요.
  • 작업 접수. 호출 성공은 job 또는 task 참조를 반환하며, 반드시 완성 파일은 아닙니다. 생성은 비동기이므로 그 식별자를 기록하세요.
  • 결과 가져오기. 모델 페이지의 응답 계약에 따라 반환된 참조로 상태를 폴링하거나 결과 URL을 가져오세요.
  • 재생. 클립을 다운로드해 보세요. 구도, 방향, 읽는 내용이 스크립트와 일치하는지 확인하세요.

이 curl 명령을 실제 식별자를 채운 초안 파일에 저장하세요. 이 명령이 대조 실험이 됩니다. Python 버전에 문제가 생기면 curl을 다시 실행해 문제가 코드에 있는지 입력에 있는지 증명하세요.

각 직조 띠는 하나의 단계, 즉 구성, 전송, 수신, 다운로드를 표시하며, 호출 재시도를 위한 루프백이 하나 있습니다.

Python으로 전환해 반복 생성하기

curl 호출이 성공하면 이를 함수로 감싸세요. 목적은 추상화를 위한 추상화가 아니라, 모든 파라미터를 명시적 인자로 만들어 클립이 호출 지점만으로 완전히 설명되게 하는 것입니다.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/generate"
API_KEY = os.environ["HIAPI_API_KEY"]

# 하나의 시리즈에서 일정하게 유지
AVATAR = "<avatar_identifier>"


def generate_clip(script: str, voice: str, aspect_ratio: str = "9:16",
                  duration: int = 30) -> dict:
    payload = {
        "model": "heygen-avatar-iv",
        "input": {
            "avatar": AVATAR,
            "script": script,
            "voice": voice,
            "aspect_ratio": aspect_ratio,
            "duration": duration,
        },
    }
    resp = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    job = generate_clip(
        script="디지털 휴먼 파이프라인의 30초 테스트입니다.",
        voice="<voice_identifier>",
    )
    print(job)

나중에 도움이 되는 설계 포인트:

  • 기본값은 가장 자주 쓰는 클립을 반영한다. 대부분의 출력이 세로 짧은 클립이라면 이를 기본값으로 두고 거의 덮어쓰지 마세요.
  • 외형은 모듈 수준에 둔다. 디지털 휴먼 선택이 한 곳에만 존재하므로 브랜드 교체는 한 줄만 바꾸면 됩니다.
  • 전체 응답을 반환한다. 즉시 URL만 추출하고 job 객체를 버리지 마세요. 로그와 재시도에 그 식별자가 필요합니다.
  • HTTP 오류 시 예외를 던진다. 배치 루프에서 조용한 실패는 크래시보다 나쁩니다.
  • 비동기 단계를 명시적으로 처리한다. 생성 함수 내부에서 sleep하지 말고 작은 poll(job_id) 헬퍼를 추가하세요.

응답 처리 로직을 모델 페이지에 기록된 계약에 고정하세요. job 상태와 결과 가져오기의 필드 이름이 여러분의 가정과 가장 어긋나기 쉬운 부분입니다.

나레이션 스크립트 작성과 리듬 제어

디지털 휴먼 영상은 오디오 우선입니다. 종이에서 읽으면 괜찮은 스크립트도 소리 내어 읽으면 너무 길어지는 경우가 많고, 생성 후 자르면 잘라낼 텍스트에 대해 렌더링 비용을 내는 셈입니다.

길이에 맞춰 먼저 쓰고, 그다음 자르기

API를 호출하기 전에 길이를 추정하세요. 편안한 말 속도는 분당 약 130–160단어이며, 시청자가 따라가야 하는 기술 콘텐츠라면 낮은 쪽을 사용하세요. 따라서 30초 클립에는 약 65–80단어, 60초 클립에는 약 130–160단어가 필요합니다. 이 예산에 맞춰 초안을 쓰고, 타이머를 켜고 소리 내어 읽은 뒤 삭감하세요. 삭감해야 한다면 단어가 아니라 문장 단위로 자르세요. 문장 단위 삭감이 리듬을 온전하게 유지합니다.

귀를 위해 쓰기

  • 짧은 문장. 문장마다 하나의 요점만 담으세요. 종속절은 이해도가 떨어지는 지점입니다.
  • 시각에만 의존하는 지시는 피한다. “아래와 같이”는 슬라이드가 없으면 통하지 않습니다.
  • 핵심을 앞에 둔다. 숏폼 시청자는 첫 몇 초에 결정하므로 주장을 첫 문장에 두세요.
  • TTS가 잘못 읽을 내용은 풀어 쓴다. 약어, 버전 문자열, 대소문자가 특이한 제품명은 발음되어야 하는 방식으로 쓰세요.

타임라인으로 리듬 제어하기

스크립트를 목표 길이에 맞춰 시간 블록으로 배치하세요:

0–5s    훅: 주장 또는 문제
5–20s   본문: 메커니즘, 두세 문장
20–28s  세부: 기억에 남길 숫자나 예시 하나
28–30s  마무리: 단일 행동 유도

이 블록 구조는 검토 산출물로도 작동합니다. 검토자는 아무것도 다시 렌더링하지 않고 특정 블록을 반려할 수 있습니다. 각 클립의 스크립트를 별도 파일에 두고 렌더링 코드와 함께 버전 관리하면 다음 섹션의 배치 루프가 완전히 재현 가능해집니다.

가로세로 비율, 길이, 출력 설정

첫 렌더링 전에 대상 플랫폼에 따라 방향과 길이를 정하세요. 완성된 클립을 두 번째 방향으로 다시 렌더링하는 것은 순수한 낭비이고, 너무 긴 클립을 다시 편집하면 오디오도 다시 생성해야 합니다.

가로세로 비율

  • 9:16 세로 — 숏폼 피드의 기본값: shorts, reels, stories, 모바일 우선 지면. 구도를 우선 이 비율로 설계하고, 가능하면 세로 마스터에서 다른 비율을 잘라내세요.
  • 16:9 가로 — 임베드 플레이어, 랜딩 페이지, 문서 영상, 프레젠테이션 상황.
  • 1:1 정사각형 — 정사각형을 선호하는 피드 지면. 보조 파생 버전으로 적합합니다.

캠페인에 두 방향이 필요하다면 같은 스크립트를 두 번 렌더링하는 대신 서로 다른 스크립트로 두 개의 별도 작업으로 취급하세요. 30초 세로 영상에 맞는 한 문장은 더 짧은 정사각형 편집에서는 빈 시간으로 남는 경우가 많습니다.

길이

길이는 그 반대가 아니라 이전 섹션의 스크립트 예산에 따라 설정하세요. 실제 낭독 길이에 맞는 길이를 전달하세요. 채워지거나 문장 중간에서 잘린 클립은 고장 난 것처럼 보입니다. 플랫폼 목표를 설정에 두어 조정하기 쉽게 하세요:

TARGETS = {
    "vertical": {"aspect_ratio": "9:16", "duration": 30},
    "horizontal": {"aspect_ratio": "16:9", "duration": 45},
}

출력

임시 결과 URL에 의존하지 말고 완성 클립을 직접 다운로드해 저장하세요. 단순한 규칙({clip_id}-{orientation}-{version}.mp4)을 쓰면 파생 버전을 추적할 수 있고 오래된 파일을 한눈에 알아볼 수 있습니다. job 식별자를 파일과 함께 기록해 모든 클립이 정확한 요청으로 되짚어질 수 있게 하세요.

과금은 요청한 생성에 대해, 즉 길이와 클립 수에 따라 부과되므로, 렌더링 전에 스크립트를 다듬는 것이 가장 저렴한 최적화입니다. 현재 요율은 가격 패널을 참고하세요.

여러 클립 배치 생성하기

쓸 수 있는 함수가 생기면 배치는 작업 목록에 대한 루프입니다. 핵심은 각 작업이 하나의 클립을 완전히 설명한다는 점입니다.

JOBS = [
    {"id": "launch-vertical", "script_file": "scripts/launch.txt",
     "voice": "<voice_a>", "aspect_ratio": "9:16", "duration": 30},
    {"id": "launch-square", "script_file": "scripts/launch_sq.txt",
     "voice": "<voice_a>", "aspect_ratio": "1:1", "duration": 20},
    {"id": "changelog-vertical", "script_file": "scripts/changelog.txt",
     "voice": "<voice_b>", "aspect_ratio": "9:16", "duration": 30},
]

results = []
for job in JOBS:
    with open(job["script_file"]) as f:
        script = f.read().strip()
    print(f"submitting {job['id']} ({len(script.split())} words)")
    resp = generate_clip(
        script=script,
        voice=job["voice"],
        aspect_ratio=job["aspect_ratio"],
        duration=job["duration"],
    )
    results.append({"id": job["id"], "job": resp})

채택할 만한 패턴:

  • 스크립트는 문자열 리터럴이 아니라 파일로. 검토하고, 비교하고, 방향 간에 재사용할 수 있습니다.
  • 단어 수 로그. 작업마다 단어 수를 출력하면 렌더링 비용을 쓰기 전에 길이를 초과할 스크립트를 발견할 수 있습니다.
  • 안정적인 job id. 출력 파일 이름과 로그에 사용하면 스무 번의 실행 중 실패한 클립을 식별할 수 있습니다.
  • 소프트 실패 후 보고. 각 제출을 try/except로 감싸 실패를 모으고 계속하세요. 잘못된 스크립트 하나가 배치 전체를 중단해서는 안 됩니다.
  • 속도 제한과 동시성 준수. 직렬로 시작하고, 직렬 실행이 안정된 뒤에만 제한된 작업 스레드 풀을 추가하세요.
  • 결과 목록 영속화. job id를 JSON 파일에 기록하면 부분 완료된 배치를 재시작하지 않고 이어서 실행할 수 있습니다.

흔한 실패 지점과 점검

다음은 가장 먼저 드러나는 문제들입니다. 각각에는 저렴한 격리 점검이 있습니다.

입력 형식 오류

스키마 오류는 가장 흔한 첫 실패입니다.점검: 같은 식별자로 원래 curl 명령을 실행하세요. curl은 성공하고 Python은 실패한다면 버그는 직렬화에 있습니다. 보통 정수 duration에 문자열을 넣었거나 스크립트 파일 끝에 줄바꿈이 더 붙은 유형 불일치입니다.

오디오와 스크립트 불일치

음성이 의도한 화면 내용과 다르게 말하거나 클립이 무음이면 오디오 그룹이 잘못된 것입니다.점검: 요청이 텍스트 기반인지 오디오 트랙 기반인지 확인하고, 그에 맞는 필드를 전달했는지 확인하세요. 오디오 트랙과 스크립트 필드를 동시에 제공하는 것이 전형적인 무음 충돌입니다. 어느 쪽이 우선인지 정하고 다른 하나를 제거하세요.

방향이 잘못되었거나 검은 여백이 생김

클립이 검은 여백이나 예상치 못한 프레임으로 돌아옵니다.점검: aspect_ratio가 실제로 페이로드에 도달했는지 확인하세요. 함수의 기본값이 전달했다고 생각한 값을 조용히 덮어쓸 수 있습니다. 보내기 전에 조립된 페이로드를 로그로 남기세요.

길이 불일치

클립이 문장 중간에서 잘리거나 끝이 늘어집니다.점검: 스크립트 단어 수와 길이 예산을 비교하세요. 목표 자체가 틀리지 않았다면 길이가 아니라 스크립트를 고치세요.

시리즈 내 외형 드리프트

같은 캠페인의 클립이 서로 다른 진행자처럼 보입니다.점검: 디지털 휴먼 식별자가 작업별 설정이 아니라 단일 상수에서 오는지 확인하세요.

출력 잘림 또는 누락

job은 성공했지만 파일이 불완전합니다.점검: 다운로드 전에 job이 최종 성공 상태에 도달했는지 확인하고, URL을 추측하지 말고 모델 페이지의 가져오기 계약을 따랐는지 확인하세요.

일반 규칙: 한 번의 테스트 클립, 한 번의 curl 요청, 한 번에 하나의 변수. 먼저 heygen-avatar-iv 모델로 짧은 세로 렌더링을 한 번 수행해 엔드투엔드로 검증한 뒤 루프를 확장하세요.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기