Hailuo 2.3 API 가이드: 텍스트 투 비디오, 이미지 투 비디오 및 Fast 버전

TL;DR

• Hailuo 2.3은 MiniMax의 비디오 모델입니다. HiAPI에서는 세 가지 엔드포인트로 제공됩니다: hailuo-2.3/text-to-video, hailuo-2.3/image-to-video, 그리고 더 저렴한 hailuo-2.3-fast/image-to-video.
• 초당이 아니라 건당 과금입니다: 6초 영상 $0.40, 10초 영상 $0.80. Fast 이미지 투 비디오는 $0.27과 $0.46입니다.
• 입력 파라미터는 매우 적습니다: prompt, duration(문자열 "6" 또는 "10"), prompt_optimizer, 이미지 투 비디오에는 image_url이 추가됩니다. 해상도, 화면 비율, seed 파라미터는 없습니다. 텍스트 투 비디오 모델 페이지 열기에서 바로 사용해 볼 수 있으며, 신규 계정에는 200 무료 크레딧이 제공됩니다.

어떤 엔드포인트를 써야 할까

	텍스트 투 비디오	이미지 투 비디오	Fast 이미지 투 비디오
모델 ID	hailuo-2.3/text-to-video	hailuo-2.3/image-to-video	hailuo-2.3-fast/image-to-video
필수 파라미터	prompt	prompt + image_url	prompt + image_url
6초 영상	$0.40	$0.40	$0.27
10초 영상	$0.80	$0.80	$0.46
이미지 입력	없음	첫 프레임 1장	첫 프레임 1장

HiAPI 실시간 가격, 2026년 10월 20일 확인. 실패한 작업은 과금되지 않습니다.

장면을 탐색할 때는 텍스트로 시작하고, 첫 프레임이 정확해야 할 때(예: 기존 제품이나 캐릭터)는 이미지로 시작하세요. 이미지 투 비디오에서는 Fast가 입력은 같으면서 3분의 1 저렴하므로, 먼저 Fast로 초안을 만들고 특정 샷에 더 많은 움직임 디테일이 필요할 때 표준 모델로 전환하면 됩니다.

텍스트 투 비디오: 실제 출력

모델 페이지에 있는 예시이며, 길이는 6초입니다:

a kung fu master practicing forms in heavy rain, water droplets scattering in slow motion, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

이 프롬프트로 생성하기 →

hailuo-2.3/text-to-video, 6초, 1366×768, 오디오 없음, $0.40.

6초 동안 이 무술가는 여러 서기 자세와 팔 공격 동작을 차례로 수행하고, 뒤에서는 비가 계속 내립니다. 카메라는 안정적으로 유지됩니다. 요청에 화면 비율 필드가 없는데도 출력은 가로 영상이며, 텍스트 투 비디오로는 세로 영상을 지정할 수 없습니다.

이미지 투 비디오: 실제 출력

이미지 투 비디오는 제공한 화면을 유지하면서 움직이게 합니다. 아래 두 예시는 모두 16:9 첫 프레임을 사용했고, 결과는 1364×768로 반환되었습니다.

첫 프레임:

steam bursts from the locomotive as it slowly starts moving, wheels turning, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

이 프롬프트로 생성하기 →

hailuo-2.3/image-to-video, 6초, 1364×768, 오디오 없음, $0.40.

역, 객차, 일몰 모두 화면과 동일하게 유지됩니다. 기관차가 앞으로 견인되고 증기가 승강장 낮은 곳으로 퍼져 나갑니다.

같은 방식으로 Fast를 쓰면 더 조용한 장면이 나옵니다:

boats rocking gently, seagulls gliding through the morning mist, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

이 프롬프트로 생성하기 →

hailuo-2.3-fast/image-to-video, 6초, 1364×768, 오디오 없음, $0.27.

움직임의 폭이 작습니다: 배는 살짝 흔들리고, 안개는 천천히 흘러가며, 끝날 무렵 갈매기 한 마리가 나타납니다. 이렇게 조용하고 분위기 중심의 샷이라면 Fast로 충분합니다.

이미지 투 비디오의 프롬프트에는 다음에 무슨 일이 일어나는지를 써야 합니다. 모델은 이미 화면을 보았기 때문에 "검은 기관차가 역에 멈춰 있다"는 아무 정보도 더하지 않습니다. "움직이기 시작하자 증기가 뿜어져 나온다"가 해야 할 일을 알려주는 문장입니다.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3/text-to-video",
    "input": {
      "prompt": "A glass of iced tea tips over in slow motion, tea splashing across a wooden table, ice cubes tumbling, macro shot",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

taskId를 받게 됩니다. data.status가 success가 될 때까지 GET https://api.hiapi.ai/v1/tasks/{taskId}를 폴링한 다음 data.output[0].url을 다운로드하세요. 영상은 몇 초가 아니라 몇 분이 걸립니다.

이미지 투 비디오는 모델을 바꾸고 이미지를 하나 추가합니다:

{
  "model": "hailuo-2.3-fast/image-to-video",
  "input": {
    "prompt": "The cat stretches, hops off the windowsill and walks toward the camera",
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "duration": "6"
  }
}

Python: 제출, 폴링, 다운로드

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, timeout_s=900, **inp):
    r = requests.post(API, json={"model": model, "input": inp}, headers=H, timeout=30).json()
    if r.get("code") != 200:
        raise RuntimeError(r)  # a 400 lists every invalid field at once
    task_id = r["data"]["taskId"]  # save this; if your script dies, poll it again instead of resubmitting
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate("hailuo-2.3/image-to-video",
               prompt="Steam bursts from the locomotive as it slowly starts moving, wheels turning",
               image_url="https://your-cdn.example.com/train.jpg",
               duration="10")  # a string, not 10

with open("hailuo.mp4", "wb") as f:
    f.write(requests.get(url, timeout=120).content)

출력 링크는 작업 완료 후 약 7일 뒤 만료되므로, 링크만 저장하지 말고 파일을 저장하세요.

파라미터

필드	필수	값	설명
prompt	예	텍스트	움직임과 카메라 움직임을 설명
image_url	이미지 투 비디오만	공개 URL 하나	배열이 아닌 단일 문자열. jpeg, png 또는 webp
duration	아니오	"6"(기본) 또는 "10"	반드시 문자열
prompt_optimizer	아니오	true(기본) / false	생성 전에 짧은 프롬프트를 확장

움직임과 카메라 움직임은 모두 프롬프트에 씁니다. motion_strength, camera_movement, resolution, aspect_ratio, seed 필드는 없습니다.

마주치게 될 오류

이 오류들은 제출 시 HTTP 400으로 반환되므로 작업이 생성되지 않고 과금도 발생하지 않습니다:

• duration: got number, want string: 6을 넘겼습니다. "6"을 넘기세요.
• duration: value must be one of '6', '10': 길이는 두 가지뿐입니다.
• image_url: missing required field "image_url": 이미지 투 비디오에는 첫 프레임이 필요합니다. 필드 이름은 단수형 image_url입니다.
• additional properties 'resolution' not allowed(또는 aspect_ratio, image_urls, seed): 해당 필드를 삭제하세요.

작업이 결국 fail로 끝나면 data.error를 읽으세요. 이미지 투 비디오에서 흔한 원인은 서버가 이미지 URL을 가져오지 못하는 경우이며, 예를 들어 비공개 스토리지 버킷이나 만료된 서명 링크가 그렇습니다.

자주 묻는 질문

Hailuo 2.3은 초당 얼마인가요?

초당 과금이 아닙니다. 건당 지불합니다: 표준 모델은 6초 $0.40, 10초 $0.80이고, Fast는 $0.27과 $0.46입니다. 환산하면 표준 모델 6초 영상은 초당 약 $0.067, Fast는 초당 약 $0.045입니다.

세로 영상을 생성할 수 있나요?

텍스트 투 비디오는 안 됩니다. 화면 비율 필드가 없고 가로 영상이 반환됩니다. 이미지 투 비디오도 마찬가지로 화면 비율 필드가 없습니다. 문서에는 세로 첫 프레임이 세로 영상을 만드는지 설명되어 있지 않으므로, 이에 기반해 개발하기 전에 $0.27로 6초 Fast 영상을 한 번 테스트해 보세요.

prompt_optimizer를 꺼야 하나요?

짧은 프롬프트는 켜 두세요. 문구를 정성껏 작성해 모델이 그대로 따르길 원할 때만 끄면 됩니다.

소리가 있나요?

위 세 예시 영상 모두 오디오 트랙이 없고, 소리를 켤 수 있는 필드도 없습니다.

Fast가 더 나쁜가요?

입력은 같고 가격은 3분의 1 저렴합니다. 위 배 예시에서는 움직임이 부드럽고 깔끔했습니다. 빠른 동작이 많은 샷이라면 두 모델에서 각각 6초 초안을 하나씩 생성해 비교한 뒤 10초 버전을 렌더링하세요.

더 많은 비디오 모델 비교: HiAPI에서 가장 저렴한 이미지 및 비디오 API. 코드 없이 Hailuo를 사용해 보려면 이미지 투 비디오 모델 페이지 열기.