heygen-avatar-v와 hiapi API로 스크립트를 립싱크 숏폼 영상으로 변환하기

숏폼 토크 콘텐츠—창업자 근황 업데이트, 제품 데모, UGC 스타일 광고 토크—는 보통 실제 사람을 섭외하고, 마이크를 준비하고, 편집을 또 한 번 해야 한다는 뜻입니다. hiapi의 heygen-avatar-v는 이 모든 과정을 API 호출 한 번으로 압축합니다: 스크립트나 오디오 파일을 보내면 자연스러운 아이들링 동작과 자막 트랙이 포함된 립싱크 아바타 영상이 돌아오고, 숏폼 피드에 바로 투입할 수 있습니다. 이 글에서는 실제 /v1/tasks 워크플로, 실제로 생성된 영상 클립, 파이프라인을 구축하기 전에 알아두면 좋은 제약 사항, 그리고 hiapi의 /api/pricing에서 실시간으로 가져온 가격을 살펴봅니다. 아바타 자체의 프롬프트 수준 스타일 기법을 원한다면 heygen-avatar-v prompt recipes에서 다루고 있으니 참고하세요—이 글은 해당 모델을 재사용 가능한 숏폼 파이프라인에 연결하는 방법에 관한 것입니다.

heygen-avatar-v가 실제로 출력하는 것

heygen-avatar-v는 Sora/Kling 같은 의미의 텍스트→비디오 생성기가 아니라 디지털 휴먼 영상 모델입니다—텍스트 스크립트나 업로드한 오디오 파일로 미리 설정된 HeyGen 아바타를 구동하고, 아바타의 입이 음성과 립싱크되며 미세한 지속 동작(눈 깜빡임, 약간의 고개 움직임, 어깨 흔들림)이 있어 정지 초상화처럼 보이지 않는 영상을 반환합니다. 이 "가만히 있어도 움직이는" 동작이 바로 쓸 만한 숏폼 클립과 티가 나는 말하는 사진 사이의 경계선입니다.

모델은 두 가지 입력으로 구동되며, 둘은 상호 배타적입니다—둘 중 하나만 보냅니다:

• prompt—텍스트 스크립트; hiapi의 TTS가 읽어 주고 립싱크를 구동합니다
• audio_url—미리 녹음한 음성 트랙(내 녹음, 클론 음색 등 무엇이든)의 공개 URL; 이것이 립싱크를 구동합니다

duration 필드는 없습니다. 클립 길이는 전적으로 스크립트나 오디오가 재생되는 시간에 달려 있습니다—40단어짜리 한 줄은 200단어짜리 한 줄보다 짧은 클립을 만듭니다. 이는 비용 계획에 중요하며 아래에서 다룹니다.

선택 필드는 스타일을 다듬는 데 사용됩니다: avatar(HeyGen 프리셋 라이브러리에서 선택), voice(prompt와 함께만 사용, audio_url과 함께 쓰면 무시됨), aspect_ratio(Reels/TikTok/Shorts용 9:16, 16:9, 1:1), resolution, background(단색 또는 장면—단, 아래 함정 참고), caption(자막 트랙 생성) 그리고 output_format(mp4 또는 투명 배경의 webm으로, 자체 장면에 합성하기 편리).

실제 클립: 스크립트 입력, 자막 포함 아바타 영상 출력

아래는 실제 heygen-avatar-v 출력입니다—아바타가 한 줄 스크립트를 말하고, 구절 사이에 눈에 띄는 아이들링 동작이 있으며, 동기화된 자막 트랙이 포함되어 있습니다:

여기서 일어나지 않는 일에 주목하세요: 아바타는 문장 사이에 굳지 않고, 자막은 나중에 붙인 것이 아니라 음성을 따라갑니다. 동작의 연속성과 타이밍이 맞춰진 자막의 조합—이것이 편집기에서 정지 아바타 이미지에 내레이션을 입히는 대신 이 모델을 선택하는 이유 전부입니다.

함정: 초기 파이프라인을 물어뜯는 두 가지 문제

caption은 하드 자막이 아니라 자막 부속 파일을 줍니다. caption: true로 설정하면 비디오 출력 외에 동기화된 .srt 파일이 반환됩니다—영상 프레임에 텍스트를 구워 넣지 않습니다. 화면에 자막 텍스트가 보이길 원한다면(대부분 숏폼 플랫폼의 그 느낌), 이 .srt 파일로 별도의 굽기 작업을 해야 합니다(ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4, 또는 플랫폼 네이티브 자막 가져오기 기능 사용). API의 "자막"을 렌더링된 화면이 아니라 데이터로 취급하세요.

background는 일러스트풍 아바타에만 적용되고 실사풍에는 효과가 없습니다. HeyGen의 아바타 라이브러리는 포토리얼 실사 아바타와 일러스트/애니메이션풍 아바타가 섞여 있습니다. background 파라미터는 일러스트풍 아바타 뒤의 장면을 성공적으로 교체하지만, 실사풍 아바타는 무엇을 전달하든 원래 녹화된 배경을 유지합니다—모델이 이를 분리하지 않습니다. 파이프라인이 모든 아바타가 배경 오버라이드를 받는다고 가정한다면, 사용할 특정 avatar ID를 먼저 테스트한 뒤 예상대로 합성된다고 가정하세요. 실사풍 아바타를 자체 배경에 올리고 싶다면 신뢰할 수 있는 방법은 output_format: webm(투명)입니다.

비용: 호출 횟수가 아니라 출력 초당 과금

hiapi의 실시간 /api/pricing에 따르면 heygen-avatar-v는 출력 초당 $0.15로 과금됩니다—해상도나 화면 비율과 무관한 단일 요율입니다. 길이 입력이 없으므로 실제 비용은 스크립트나 오디오가 재생되는 시간에 달려 있습니다:

스크립트 길이(대략)	출력 길이	비용
짧은 훅 문장	약 5초	$0.75
숏폼 한 비트	약 10초	$1.50
여러 문장 세일즈 피치	약 20초	$3.00
풀 30초 광고 토크	약 30초	$4.50

비용이 사전에 설정한 파라미터가 아니라 음성 길이에 따라 늘어나므로, 클립이 렌더링된 뒤 청구서를 보고 알기보다는 작업을 제출하기 전에 스크립트 시간을 재는 것이 실용적입니다(소리 내어 읽어 보거나 TTS 길이 추정기로 돌려 보기).

파이프라인: 제출, 폴링, 만료 전 다운로드

heygen-avatar-v는 hiapi의 비동기 /v1/tasks 엔드포인트에서 실행됩니다—플랫폼의 다른 모든 작업 기반 모델과 마찬가지로 "먼저 생성 후 폴링" 형태입니다. 이 워크플로에 특유한 세부 사항 하나: 작업이 handling과 success 사이에 archiving 단계를 거치며, 이때 플랫폼이 비디오와 자막 부속 파일을 마무리하고 있으므로 폴링 루프에서 archiving을 종료 상태로 취급하면 안 됩니다.

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

규모 있게 사용할 때 건너뛸 수 없는 두 가지 운영 설명:

• 즉시 다운로드하세요. hiapi의 모든 작업 출력과 마찬가지로 반환된 URL에는 expireAt이 있어 장기 링크로 적합하지 않습니다—작업이 성공하자마자 바이트(비디오와 .srt)를 자체 스토리지로 가져오세요.
• "스키마 확인"을 위해 최소 필드만 담은 페이로드를 보내지 마세요. 엄밀히는 prompt나 audio_url만 필수이고 다른 필드는 조용히 기본값을 쓰기 때문에, {"prompt": "test"}만 담은 페이로드는 400을 반환하지 않습니다—실제로 과금되는 렌더링을 발행합니다. 필드 이름을 검증하려면 문서와 대조하거나 일부러 잘못된 값을 넣어 4xx 응답을 받으세요. 실제 엔드포인트에 대고 필드를 생략하지 마세요.

FAQ

hiapi의 TTS 대신 내 목소리를 쓸 수 있나요? 가능합니다—prompt 대신 audio_url을 전달하고 녹음의 공개 URL을 주면, 아바타가 텍스트에서 음성을 합성하는 대신 그 오디오 트랙에 맞춰 립싱크합니다.

caption 옵션이 자막을 영상에 구워 넣나요? 아니요. caption: true는 출력 비디오의 오디오와 동기화된 별도의 .srt 파일을 반환합니다. 화면에 자막 텍스트를 원한다면 후처리 단계로 직접 구워 넣어야 합니다.

클립 길이를 제어할 수 있나요? 직접적으로는 불가능합니다—duration 파라미터가 없습니다. 출력 길이는 스크립트 길이(prompt 사용 시) 또는 오디오 파일 길이(audio_url 사용 시)에 의해 결정됩니다.

지정한 배경이 왜 나타나지 않나요? background는 HeyGen 라이브러리의 일러스트/애니메이션풍 아바타에만 효과가 있습니다. 실사 포토리얼 아바타는 원래 녹화된 배경을 유지합니다; 이 경우 output_format: webm으로 투명 출력을 얻어 직접 합성하세요.

어떤 해상도와 화면 비율을 지원하나요? 최대 4K, 9:16, 16:9, 1:1 화면 비율 옵션을 지원합니다—세로형 숏폼 피드부터 와이드스크린, 정사각형 광고까지 커버합니다.

핵심 요점

hiapi에서 숏폼 아바타 파이프라인을 구축하는 것은 추측이 아니라 몇 가지 구체적 사실로 요약됩니다: 비용은 출력 초당 $0.15(그러므로 제출 후가 아니라 제출 전에 스크립트 시간을 재세요), 자막 출력은 직접 구워 넣어야 하는 .srt 부속 파일, 배경 교체는 일러스트풍 아바타에만 유효, 폴링 루프는 archiving을 handling과 마찬가지로 비종료 상태로 취급해야 합니다. 예산을 하드코딩하기 전에 hiapi의 가격 페이지에서 현재 수치를 확인하고, 전체 필드 참조는 모델 페이지를 보세요. 시작할 준비가 되었다면 대시보드에서 API 키를 받아 짧은 스크립트로 시작하세요—5초 출력만으로도 아바타, 화면 비율, 자막 처리가 모두 정상인지 확인한 뒤 전체 배치로 확장할 수 있습니다.