사용 가이드

hiapi에서 hailuo-2.3-fast/image-to-video로 숏폼 영상 일괄 생성하기

Aug 4, 2026

숏폼 영상의 성패는 반복 속도에 달려 있습니다. TikTok이나 Reels용 파이프라인을 운영한다면 시네마틱한 4K 결과물은 필요 없습니다. 필요한 것은 제품 정지 이미지를 1분 이내에 쓸 만한 클립으로 바꿔 주는 모델이며, 최적의 버전을 고르기 전에 수십 개의 변형을 돌려볼 수 있을 만큼 비용이 낮아야 합니다. 바로 이것이 hailuo-2.3-fast/image-to-video의 포지션입니다. hailuo-2.3의 Fast 티어 형제 버전으로, 가격과 튜닝 모두 고생산·폐기 가능한 다회 시도 워크플로에 맞춰져 있습니다.

이 가이드에서는 이 모델을 일괄 숏폼 영상 엔진으로 활용하는 방법을 다룹니다. 소스 정지 이미지를 고르는 법, 비동기 작업 API로 구동하는 법, 지키지 않으면 400 오류를 맞게 되는 스키마 세부 사항을 검증하는 법, 그리고 TikTok/Reels 규모로 운영할 때의 경제성을 생각하는 법입니다.

모델이 제공하는 것

hailuo-2.3-fast/image-to-video는 정지 이미지 한 장과 프롬프트를 받아 짧은 영상 클립으로 애니메이션화합니다. hailuo-2.3-fast/image-to-video 모델 페이지에 있으며, hiapi의 모든 모델과 마찬가지로 통합 /v1/tasks 비동기 엔드포인트로 호출합니다. 작업을 POST하고 완료될 때까지 폴링(또는 콜백 등록)한 뒤, 단기 유효한 출력 URL에서 영상을 가져오면 됩니다.

작성 시점에 라이브 API로 검증한 내용:

입력: 이미지 한 장(image_url) + 원하는 움직임을 설명하는 텍스트 프롬프트
출력: MP4, 고정 길이 6s 또는 10s (임의 길이 미지원)
가격: 초당 과금이 아닌 영상당 정액 — 6초 클립 $0.27, 10초 클립 $0.46
처리 시간: 테스트 클립 기준 엔드투엔드(제출 → 성공) 약 80초 소요

영상당 정액 과금은 일괄 작업의 핵심 포인트입니다. 6초 시도는 프롬프트가 첫 번째에 움직임을 잡아내든 네 번째에야 잡아내든 비용이 같습니다. Fast 티어 가격이라면 같은 키 비주얼에 5-6개 변형을 돌려 가장 매끄러운 움직임을 찾아도 대부분의 고급 영상 모델 1회 시도 비용보다 낮습니다. 일괄 예산을 짜기 전에 가격 페이지에서 현재 수치를 확인하세요. 가격은 변동됩니다.

전체 파라미터 레퍼런스, 더 긴 길이 옵션, 또는 비 Fast hailuo-2.3 티어와의 나란히 비교가 필요하다면 hailuo-2.3-fast/image-to-video API 통합 튜토리얼을 참고하세요. 이 가이드는 원시 API 레퍼런스가 아니라 일괄/워크플로 관점에 초점을 둡니다.

워크플로: 정지 이미지 → 숏폼 클립

숏폼의 공식은 간단합니다. 이미 가진 정지 이미지(제품 사진, 생성된 히어로 샷, 브랜드 소재)에서 출발해 모델이 움직임을 더하게 합니다. 느린 푸시인, 미세한 회전, 흔들리는 분위기 같은 것들이며, 처음부터 영상을 생성하는 것이 아닙니다. 이렇게 하면 시각적 정체성(같은 제품, 같은 조명, 같은 구도)을 고정하면서 정적 게시물이 아닌 콘텐츠를 만들 수 있습니다.

실제 실행 사례입니다. 조명 받침대 위에 놓인 세로형(9:16) 운동화 정지 이미지를 느린 푸시인과 부드러운 회전을 설명하는 움직임 프롬프트로 구동했습니다.

소스 정지 이미지와 전체 요청:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast/image-to-video",
    "input": {
      "prompt": "Slow smooth push-in on a chunky retro basketball sneaker in wolf-gray suede with volt yellow laces, floating above a wet concrete pedestal, subtle rotation revealing the side panel, mist drifting through teal-to-amber rim light, dust particles catching the light, stable cinematic camera movement, premium commercial product-video finish",
      "image_url": "https://static.hiapi.ai/gallery/2026/07/c2e71481d2eb81a7.jpg",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

응답:

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

해석이 끝날 때까지 폴링:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KZ5FJV0TB8EYKDCV58FQ1F2X \
  -H "Authorization: Bearer $HIAPI_API_KEY"

{
  "status": "success",
  "output": [{"type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786421652}]
}

그 output[0].url은 임시입니다. 즉시 다운로드해 자체 스토리지로 옮기세요. 핫링크하지 말고, 안정적인 URL이라고 믿고 DB 필드에 저장하지 마세요.

입력 스키마 (라이브 API로 검증 완료)

이 모델의 스키마는 플랫폼의 다른 영상 모델에서 기대하는 것보다 훨씬 좁습니다. 화면비 제어도, 해상도 티어도, seed도 없습니다.

필드	타입	제약	필수
`prompt`	string	움직임/장면 설명	예
`image_url`	string	단수 — 공개 URL 하나, 배열 아님	예
`duration`	string	열거형 `"6"` 또는 `"10"` — 문자열이어야 하며 숫자 아님	예
`prompt_optimizer`	boolean	플랫폼이 프롬프트를 재작성/강화하도록 허용	아니오

다른 모델의 가정을 그대로 가져오면 400을 맞게 되는 두 가지 함정이 있습니다:

image_url은 단수이며 image_urls가 아닙니다. hiapi의 다른 여러 i2v 모델은 참조 이미지 배열을 받지만 이 모델은 한 장만 받습니다. 배열을 보내면 친절한 타입 변환 대신 필드 누락 오류가 납니다.
duration은 문자열 "6" 또는 "10"이어야 하며 숫자 6이 아닙니다. 숫자 6을 보내면 duration: got number, want string이 반환됩니다. 또한 이 두 값 열거형 밖의 값은 허용되지 않습니다. 이 티어에는 임의 길이 제어가 없습니다.

aspect_ratio, resolution, seed, watermark를 보내면 — 형제 모델에서는 흔한 필드들이지만 — additional properties ... not allowed와 함께 바로 거부됩니다. 모델은 입력 이미지의 화면비를 상속하므로, Reels/TikTok용 9:16 출력이 필요하다면 제출 전에 소스 정지 이미지를 9:16으로 자르거나 생성하세요(위의 운동화 정지 이미지가 바로 그렇게 했습니다).

엔드투엔드 Python

import requests
import time

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "your-api-key"

def make_short_clip(prompt: str, image_url: str, out_path: str, duration: str = "6"):
    resp = requests.post(
        API_BASE,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "model": "hailuo-2.3-fast/image-to-video",
            "input": {
                "prompt": prompt,
                "image_url": image_url,
                "duration": duration,  # must be a string: "6" or "10"
                "prompt_optimizer": True,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API_BASE}/{task_id}",
                             headers={"Authorization": f"Bearer {API_KEY}"},
                             timeout=30).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(8)

    video_url = task["output"][0]["url"]  # temporary link — download immediately
    video_bytes = requests.get(video_url, timeout=120).content
    with open(out_path, "wb") as f:
        f.write(video_bytes)
    return out_path

진짜 일괄 실행 — 예를 들어 같은 소스 정지 이미지에 6개 프롬프트 변형을 테스트해 가장 매끄러운 움직임을 고르는 경우 — 에서는 이 함수를 프롬프트 목록에 대한 루프로 감싸고, 각 task_id를 순차적으로 블로킹하지 말고 독립적으로 확인하세요. 클립당 약 80초를 기준으로 볼 때, 여러 개를 병렬로 돌리는 것이 Fast 티어를 실제로 빠르게 느껴지게 하는 방법입니다.

자주 묻는 질문

출력 화면비를 제어할 수 있나요? 아니요 — 이 모델에는 aspect_ratio 필드가 없으며 보내면 400이 반환됩니다. 출력은 입력 이미지의 화면비를 따르므로 제출 전에 원하는 비율로 소스 정지 이미지를 준비하세요(Reels/TikTok은 9:16, 피드 게시물은 1:1).

왜 요청이 "got number, want string"과 함께 실패하나요? duration을 JSON 숫자로 보냈기 때문입니다. 문자열 "6" 또는 "10"이어야 하며, 이것이 유일한 두 유효 값입니다.

hailuo-2.3/image-to-video(비 Fast)와 같은 모델인가요? 아니요 — Fast 티어는 hiapi에서 별도로 가격이 책정된 독립 모델이며, 자체 스키마를 가지고 표준 티어가 아닌 속도와 비용에 맞춰 튜닝되었습니다. 일괄이 아닌 레퍼런스 워크스루가 필요하다면 전체 통합 튜토리얼을 참고하세요.

실제 사진 대신 생성된 이미지를 넣어도 되나요? 네 — 소스 정지 이미지는 hiapi(또는 다른 곳)의 어떤 이미지 모델에서 나온 것이든 공개적으로 접근 가능한 URL이기만 하면 됩니다. 다른 포맷용으로 이미 만들어 둔 정지 이미지(제품 키 비주얼, 포스터)를 사용하는 것이 별도 크리에이티브 프로세스 없이 숏폼을 가장 빨리 얻는 방법입니다.

가격이 해상도에 따라 달라지나요? 이 모델에는 해상도 파라미터가 없으므로 입력 이미지 해상도와 무관하게 길이당 정액입니다. 작성 시점 기준 6s $0.27, 10s $0.46입니다. 가격 페이지에서 확인하세요.

핵심 요약

hailuo-2.3-fast/image-to-video는 정지 이미지 한 장을 6s 또는 10s MP4로 만들며, 초당 과금이 아닌 영상당 정액($0.27 / $0.46)이라 소스 이미지마다 여러 프롬프트 변형을 돌려볼 수 있을 만큼 저렴합니다.
스키마는 의도적으로 좁습니다: prompt, image_url(단수), duration(문자열 열거형 "6"/"10"), 그리고 선택적 prompt_optimizer — 화면비, 해상도, seed 제어는 없습니다.
출력은 입력 이미지의 화면비를 상속하므로 제출 전에 소스 정지 이미지를 9:16(또는 플랫폼에 필요한 비율)으로 준비하세요.
가장 흔한 두 통합 오류는 image_url을 배열로 보내는 것과 duration을 문자열이 아닌 숫자로 보내는 것입니다.
일괄 숏폼 워크플로에서는 영상당 정액과 약 80초의 처리 시간 덕분에 자료마다 생성 요청을 한 번만 제출하는 대신 여러 시도를 생성해 최고의 움직임을 고르는 것이 가능합니다.