튜토리얼

Creatify Boreal API 사용 방법: 텍스트, 이미지 및 오디오로 비디오 생성하기

Oct 23, 2026

creatify-boreal은 hiapi의 비디오 모델로, 음성과 사운드가 이미 믹싱된 완성 클립을 반환합니다. 하나의 모델 id가 세 가지 시작점을 지원합니다: 프롬프트만, 프롬프트와 참조 이미지, 또는 프롬프트와 직접 만든 내레이션 오디오. 이 가이드에서는 요청, 폴링 루프, 그리고 실제로 한 번 생성 작업을 실행한 결과를 보여줍니다.

API 키는 hiapi 대시보드에서 발급받아야 합니다. 모든 호출은 통합 작업 엔드포인트 POST /v1/tasks를 통해 이루어집니다.

입력 필드

이 필드들은 라이브 모델 페이지와 대조하고, /v1/tasks에 의도적으로 유효하지 않은 값을 보내 검증했습니다. 유효하지 않은 값은 400을 반환하며 과금되지 않습니다.

필드	필수	허용 값
`prompt`	예	텍스트, 최대 5000자
`image_url`	아니오	JPG/PNG/WebP, 10 MB; 주체와 구도를 설정
`audio_url`	아니오	MP3/WAV/M4A, 15 MB; 처음 `duration`초만 사용
`negative_prompt`	아니오	최대 2000자
`resolution`	아니오	`720p`, `1080p`, `2k`
`aspect_ratio`	아니오	`auto`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
`duration`	아니오	정수 초, 1 ~ 20

이 세 가지 모드는 별도의 모델 id가 아닙니다. 텍스트로 비디오를 생성할 때는 image_url과 audio_url을 생략하고, 이미지로 비디오를 생성할 때는 image_url을 추가하며, audio_url을 추가하면(보통 이미지도 함께 제공) 등장인물이 내레이션을 따라 말합니다.

최소 동작 요청

curl -X POST 'https://api.hiapi.ai/v1/tasks' \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "creatify-boreal",
    "input": {
      "prompt": "세로형 셀피 스타일 UGC 비디오: 한 젊은 여성이 밝은 침실에서 부드러운 핑크색 립스틱을 들어 올리며 카메라를 보며 말한다: \"좋아요, 이게 겨울을 버티게 해준 유일한 립스틱이에요.\" 자연스러운 방의 환경음.",
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "duration": 4
    }
  }'

응답은 작업 id를 제공합니다:

{"code":200,"data":{"taskId":"tk-hiapi-01M5MJC8NG8E1E0XN9NEJRDBQH"},"message":"success"}

Python: 제출 및 폴링

import os, time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def create(payload: dict) -> str:
    r = requests.post(BASE, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id: str, every: int = 10, limit: int = 900) -> dict:
    start = time.time()
    while time.time() - start < limit:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except (requests.RequestException, ValueError):
            time.sleep(every)  # 일시적 네트워크 오류: 같은 id로 계속 폴링
            continue
        if d["status"] == "success":
            return d
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

task_id = create({
    "model": "creatify-boreal",
    "input": {
        "prompt": "세로형 셀피 스타일 UGC 비디오: 한 젊은 여성이 부드러운 핑크색 립스틱을 들어 올리며 카메라를 보며 말한다: \"좋아요, 이게 겨울을 버티게 해준 유일한 립스틱이에요.\" 자연스러운 방의 환경음.",
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 4,
    },
})
result = wait(task_id)
print(result["output"][0]["url"])

상태는 handling, archiving을 거쳐 success로 이어집니다. 비디오 URL은 data.output[0].url에 있습니다.

이미지 및 오디오 모드

이미지로 비디오를 생성할 때는 필드를 하나 더 추가합니다:

{"model": "creatify-boreal",
 "input": {"prompt": "이 여성이 부엌에서 카메라를 보며 미소 지으며 말한다: \"커피를 이 오트 라떼 블렌드로 바꿨어요.\" 자연스러운 부엌 환경음.",
           "image_url": "https://your-cdn.example/presenter.jpg",
           "resolution": "720p", "duration": 8}}

오디오 구동 모드는 내레이션 파일을 가리키는 audio_url을 추가합니다. 모델 페이지에서는 내레이션이 비디오에 유지되고 입술이 내레이션 동작을 따라가며, 오디오의 처음 duration초만 사용된다고 설명하므로 duration을 원하는 클립 길이로 설정해야 합니다. 모델 페이지의 오디오 예시는 오디오와 참조 이미지를 함께 사용하지만, 저는 이미지와 오디오 조합의 생성을 직접 실행하지 않았으므로 이 조합은 이 글에서 문서화된 내용일 뿐 검증된 것은 아닙니다.

실제 실행 결과

저는 위의 요청(순수 텍스트, 720p, 9:16, 4초)을 실행했습니다.

생성 시간: 작업은 handling 상태에서 약 283초, 그다음 archiving 상태에서 약 10초를 보냈습니다. 4초 클립이라도 초 단위가 아니라 분 단위로 계획해야 합니다. 짧은 타임아웃 대신 10초마다 폴링하거나 콜백을 사용하세요.
출력 파일: 720x1280 MP4, H.264 비디오 24 fps 및 AAC 오디오 트랙, 길이 4.04초. 요청에 오디오 필드가 없었는데도 오디오가 존재하며, 이는 모델의 기본 사운드 디자인에 부합합니다.
임시 URL: 출력 URL은 temp.hiapi.ai에 있으며 약 7일 후 만료되는 expireAt이 있습니다. 페이지에서 링크하지 말고 파일을 다운로드해 직접 저장하세요.
비용 형태: 초 단위로 과금되며 resolution에 따라 달라지므로(가격 페이지 참조), 프롬프트를 반복할 때 가장 저렴한 방법은 720p와 짧은 duration으로 테스트한 뒤 1080p 또는 2k로 최종 버전을 다시 렌더링하는 것입니다.

제가 겪은 함정

잘못된 값은 빠르게 실패하며 무료입니다. aspect_ratio: "7:5", duration: 25 또는 resolution: "4k"를 보내면 모두 HTTP 400 INVALID_REQUEST를 반환하며, 메시지에 허용 값('auto', '16:9', '9:16', '1:1', '4:3', '3:4', 최대 20, 그리고 '720p', '1080p', '2k')이 나열됩니다. 이것을 활용해 제출 전에 자체 폼을 검증하세요.
잘못된 미디어 URL은 나중에 폴링할 때 실패합니다. 저는 audio_url: "https://example.com/a.mp3"(실제 오디오 파일이 아님)를 제출했습니다. 생성 호출은 HTTP 200과 작업 id를 반환했지만 약 15초 후 작업이 status: "fail" 및 error.code: "INVALID_REQUEST"로 종료되었습니다. 따라서 생성 시 200이 반환되었다고 해서 미디어가 사용 가능하다는 뜻은 아닙니다. 항상 최종 상태를 확인하고 data.error를 읽으세요. 이 경우 실패는 HTTP 오류가 아니라 HTTP 200 폴링 응답 내부에 표시되었습니다.
실패는 status: "fail"이며 HTTP 상태가 아닙니다. 폴링 요청 자체는 200을 반환하므로 data.status를 확인하세요.