hiapi API로 omnihuman-1.5 사용하는 방법: curl, Python 및 바로 실행 가능한 요청

omnihuman-1.5는 인물 사진 한 장과 오디오 한 개를 받아 입모양이 동기화된 말하는 영상을 생성합니다. hiapi에서 이 모델은 다른 모든 미디어 모델과 마찬가지로 동일한 비동기 작업 프로토콜 위에서 동작합니다. 먼저 POST /v1/tasks를 한 번 호출해 작업을 생성한 다음, 영상 URL이 준비될 때까지 폴링하거나(또는 웹훅을 수신할 때까지) 기다립니다. 본 가이드는 실제 요청 스키마를 사용하며, 온라인 API와 필드 단위로 대조 검증했기 때문에 아래 curl 및 Python 코드는 단순한 예시가 아니라 그대로 복사해서 실행할 수 있습니다.

무엇을 만들게 될까요

얼굴 이미지와 음성 트랙을 omnihuman-1.5에 전송하고, 해당 얼굴이 오디오에 맞춰 말하며 입모양이 동기화된 MP4 파일을 반환하는 스크립트입니다. 영상 클립 길이는 오디오를 따릅니다. 설정할 수 있는 duration 필드는 없습니다.

사전 준비 사항

1. hiapi API 키. dashboard에서 생성하세요. 매 요청마다 Bearer 토큰으로 전송됩니다. 요청 헤더 형식은 인증 문서를 참고하세요.
2. 공개적으로 접근 가능한 이미지 URL과 오디오 URL. omnihuman-1.5는 서버 측에서 두 URL을 모두 다운로드하므로, 여러분의 컴퓨터에서 익명으로 열 수 있는 http(s) URL이면 충분합니다. localhost 경로나 작업 도중 만료되는 서명 URL은 사용할 수 없습니다.

이게 전부입니다. SDK도 필요 없고, 키 외에는 계정도 필요하지 않습니다.

입력 스키마

omnihuman-1.5는 엄격한 input 객체를 받습니다. 알 수 없는 필드는 거부되므로, 사용 가능한 필드는 아래가 전부입니다:

필드	유형	필수 여부	설명
image_url	string	예	인물 사진 URL. 선명하고 정면을 향한 단일 얼굴이 가장 좋습니다.
audio_url	string	예	입모양 동기화에 사용할 음성 트랙. 출력 길이를 결정합니다.
prompt	string	아니요	선택적 모션/표정 가이드.
resolution	string	아니요	"720p" 또는 "1080p".

텍스트 전용 모드는 없습니다: audio_url은 필수입니다. 스크립트만 있다면 먼저 음성을 생성한 뒤(TTS 모델 또는 heygen-avatar-v 같은 텍스트 기반 디지털 휴먼 사용) 생성된 오디오 URL을 여기에 전달하세요.

최소 실행 예제(curl)

작업 생성:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omnihuman-1.5",
    "input": {
      "image_url": "https://example.com/portrait.jpg",
      "audio_url": "https://example.com/voiceover.mp3",
      "resolution": "720p"
    }
  }'

응답에는 작업 id가 포함됩니다:

{ "code": 200, "data": { "taskId": "b3f1c2e8-...", "status": "pending" } }

작업이 종료 상태에 도달할 때까지 폴링합니다:

curl -s https://api.hiapi.ai/v1/tasks/b3f1c2e8-... \
  -H "Authorization: Bearer sk-YOUR_KEY"

완료되면 data.status가 "success"가 되고, 영상은 data.output[0].url에 있습니다:

{
  "code": 200,
  "data": {
    "taskId": "b3f1c2e8-...",
    "status": "success",
    "output": [
      { "url": "https://temp.hiapi.ai/.../omnihuman.mp4", "expireAt": 1760000000 }
    ]
  }
}

해당 output URL은 임시입니다(expireAt 포함). 작업이 성공하면 즉시 MP4를 다운로드하세요. 프로덕션 환경에서 이 주소를 직접 핫링크하지 마세요.

Python에서의 동일한 호출

import time
import requests  # pip install requests

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}


def create_task() -> str:
    payload = {
        "model": "omnihuman-1.5",
        "input": {
            "image_url": "https://example.com/portrait.jpg",
            "audio_url": "https://example.com/voiceover.mp3",
            "resolution": "720p",
        },
    }
    r = requests.post(API, headers=HEADERS, json=payload, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait_for_video(task_id: str, timeout: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"omnihuman-1.5 task failed: {data.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout}s")


if __name__ == "__main__":
    tid = create_task()
    print("task:", tid)
    video_url = wait_for_video(tid)
    # URLs expire — persist the bytes immediately.
    mp4 = requests.get(video_url, timeout=120).content
    with open("talking_head.mp4", "wb") as f:
        f.write(mp4)
    print("saved talking_head.mp4")

프로덕션 적용

빈번한 폴링보다 콜백을 우선 사용하세요. 최상위 callback 객체를 추가하면, hiapi가 폴링을 기다리게 하지 않고 완료된 작업을 여러분의 엔드포인트로 POST합니다:

{
  "model": "omnihuman-1.5",
  "input": {
    "image_url": "https://example.com/portrait.jpg",
    "audio_url": "https://example.com/voiceover.mp3",
    "resolution": "1080p"
  },
  "callback": { "url": "https://your.app/webhooks/hiapi", "when": "final" }
}

when은 "final"만 허용하며, 성공과 실패 시 모두 트리거됩니다. 따라서 웹훅은 data.status에 따라 분기 처리해야 합니다. 전달되는 body는 GET /v1/tasks/{id}로 받는 것과 동일한 객체입니다. 전달은 최소 1회(at-least-once) 의미론이므로 taskId 기준으로 중복 제거하세요.

일시적 오류에서 절대 재제출하지 마세요. 폴링 요청이 타임아웃되거나 연결이 끊기면 동일한 taskId로 다시 폴링하세요. POST /v1/tasks를 다시 호출하지 마세요. 재제출하면 두 번째 과금 작업이 시작됩니다. taskId를 받은 즉시 저장하세요.

세 가지 실패 형태를 각각 처리하세요:

• 인증 실패 → HTTP 401, body {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. 키를 수정하세요. 재시도하지 마세요.
• 잘못된 요청(누락/유효하지 않은 필드) → HTTP 400, body {"code": 400, "error_code": "INVALID_REQUEST", "message": "..."}. message가 문제가 된 필드를 알려줍니다. 수정 후 다시 전송하세요.
• 시작되었지만 실패한 작업 → HTTP 200이고 data.status == "fail"이며 data.error가 포함됩니다. 가장 흔한 원인은 서버가 image_url/audio_url을 다운로드하지 못하는 것입니다. 두 URL 모두 공개 접근 가능하고 여전히 유효한지 확인하세요. 항상 HTTP 상태 코드만이 아니라 data.status에 따라 분기 처리하세요.

가격은 출력 초 단위로 과금되며 pricing 페이지에 명시되어 있습니다. 클립 길이가 오디오를 따르므로 비용은 오디오 길이에 따라 달라집니다.

관련 가이드

• 통합 비동기 API 소개 —— 모든 모델이 공유하는 /v1/tasks 생성 및 폴링 계약.
• 빠른 시작 —— 첫 hiapi 요청을 엔드투엔드로 완료하기.
• HeyGen Avatar IV API 튜토리얼 —— 또 다른 사진→말하는 영상 모델로, 입모양 동기화 방식을 비교해 볼 수 있습니다.
• HeyGen Avatar V —— 오디오 파일이 없을 때 스크립트 기반(텍스트→영상)으로 사용할 수 있는 디지털 휴먼.

자주 묻는 질문

오디오 파일 대신 텍스트로 omnihuman-1.5를 구동할 수 있나요? 아니요. audio_url은 필수이며, 모델은 해당 오디오에 입모양을 동기화합니다. 스크립트에서 영상으로 가는 흐름이 필요하다면 먼저 음성을 합성하거나(임의의 TTS), heygen-avatar-v 같은 텍스트 기반 디지털 휴먼을 사용한 뒤 오디오 URL을 여기에 전달하세요.

출력 영상은 얼마나 긴가요? 오디오 클립을 따릅니다. duration 파라미터는 없습니다. 12초 음성 트랙은 대략 12초 영상을 생성합니다.

어떤 이미지가 가장 좋은 결과를 내나요? 공개 URL에 있는, 조명이 선명하고 정면을 향한 단일 인물 사진입니다. 단체 사진이나 얼굴이 심하게 가려진 경우 입모양 동기화 품질이 떨어집니다.

720p인가요, 1080p인가요? 둘 다 resolution에 사용할 수 있습니다. 반복 작업 시에는 720p로 시작하고, 최종 렌더링 시 1080p로 전환하세요. 해상도가 높을수록 초당 비용이 더 높습니다. pricing을 참고하세요.

작업이 즉시 status: "fail"을 반환합니다. 왜 그런가요? 거의 항상 서버가 입력 URL 중 하나를 가져오지 못한 경우입니다. image_url과 audio_url이 공개 접근 가능한지(시크릿 창에서 열어보세요) 만료되지 않았는지 확인하세요. data.error 메시지가 원인을 좁히는 데 도움이 됩니다.

폴링이 필요한가요, 아니면 webhook을 쓸 수 있나요? 둘 다 가능합니다. 간단한 스크립트는 GET /v1/tasks/{id}로 폴링하면 됩니다. 프로덕션에서는 callback.url을 등록하고 when을 "final"로 설정하면 폴링 루프를 유지할 필요가 없습니다.