Hailuo API 사용법: MiniMax H3 Python 가이드와 3가지 영상 모드 실측

Hailuo API는 MiniMax의 영상 API이고, 현재 모델은 Hailuo 01과 02 다음 세대인 MiniMax H3(MiniMax-H3)입니다. 모든 호출은 비동기입니다. 작업을 만들고, 폴링하고, MP4를 내려받습니다. 2026년 10월 26일, 5초 768P 영상은 세 모드 모두 35초에서 42초 만에 돌아왔고, 모두 소리가 들어 있었습니다.

먼저 결론

• 모델: MiniMax 자체 API에서는 MiniMax-H3이고 2026년 7월 31일에 발표됐습니다(릴리스 노트). OmniaKey에서는 minimax-h3이며 세 가지 작업 유형이 id 하나를 씁니다(영상 문서).
• 설정할 값: resolution(필수)에 "768P" 또는 "2K", duration에 4에서 15 사이의 정수 초, aspect_ratio(영상 문서).
• 가격: 768P는 초당 $0.08, 5초면 $0.40, 2K는 초당 $0.13입니다. MiniMax 정가입니다(가격, 2026년 10월 26일 확인). OmniaKey 요금은 모델 페이지에 있습니다.
• 시간과 소리: 영상 한 편당 35초에서 42초, 모두 스테레오 소리가 들어 있습니다. V2 생성 문서에는 소리를 끄는 스위치가 없습니다(생성 문서).

공식 Hailuo API가 있나요?

있습니다. MiniMax가 platform.minimax.io에서 제공하고, 현재 모델은 MiniMax H3이며 API id는 MiniMax-H3입니다(모델 목록, 2026년 10월 26일 확인).

MiniMax의 발표는 H3를 Hailuo 01과 Hailuo 02 다음 세대로 소개합니다(발표). 예전 모델도 API에 남아 있고 MiniMax-Hailuo-2.3, MiniMax-Hailuo-02로 호출합니다(V1 문서).

이름은 페이지마다 다릅니다. MiniMax 문서는 "MiniMax H3", API의 모델 설명은 "Hailuo-03"(생성 문서), 발표에서 체험을 권하는 Hailuo AI 앱은 "Hailuo 3.0"이라고 씁니다(앱). "Hailuo 3"은 공식 이름이 아닙니다.

키는 Account > API Keys에서 만들고, 과금은 사용한 만큼 내는 방식입니다(API FAQ). MiniMax의 영상 패키지는 예전 모델을 대상으로 하고 H3는 포함하지 않습니다(가격).

MiniMax는 H3를 네 가지로 제공합니다(생성 문서).

MiniMax 자체 API에서는 호출이 세 단계입니다(영상 가이드).

• POST https://api.minimax.io/v2/video_generation이 task_id를 돌려줍니다(생성 문서).
• GET /v2/query/video_generation/{task_id}를 succeeded가 될 때까지 폴링한 뒤 content.url을 내려받습니다(조회 문서).
• 최근 7일 작업만 조회할 수 있고, 다운로드 URL이 얼마나 유지되는지는 MiniMax가 공개하지 않았습니다(조회 문서).

V1(Hailuo 2.3과 02)은 작업 id를 경로가 아니라 ?task_id= 쿼리 파라미터로 넘기므로 두 흐름은 따로 봅니다(V1 문서).

OmniaKey는 MiniMax H3 API 접근을 제공하므로 이 예제는 그 경로로 실행했습니다. 흐름은 같습니다. POST https://api.omniakey.com/v1/media/tasks를 Idempotency-Key 헤더와 함께 호출하면 202와 id가 돌아오고, GET /v1/media/tasks/{id}로 폴링합니다(미디어 개요). 같은 흐름을 Grok Imagine Video API 가이드에서도 씁니다. 아래 가격은 모두 MiniMax 정가입니다.

어떤 파라미터를 설정할 수 있나요?

• resolution은 필수입니다. 1080P와 4K는 400 model_price_error로 실패하고(영상 문서), V2에는 H3용 1080P가 없습니다(생성 문서). 세 모드는 모두 768P로 실행했고 2K는 시험하지 않았습니다.
• duration은 4에서 15 사이의 정수 초입니다(영상 문서). MiniMax-H3-Max는 5초부터 시작하고 4를 넣으면 거부합니다(생성 문서).
• aspect_ratio는 adaptive, 16:9, 9:16, 1:1, 4:3, 3:4, 21:9를 받습니다(영상 문서). MiniMax API에서 텍스트→영상은 고정 비율이 필요하고, 이미지→영상은 이미지 모양을 따릅니다(생성 문서). 이미지→영상에서는 비율을 넣지 않았고, 영상은 원본 이미지 모양인 1376×768을 유지했습니다.
• input.media[]는 이미지→영상에서 first_frame과 선택적인 last_frame, 레퍼런스→영상에서 reference_image, reference_video, reference_audio를 받습니다. 두 종류는 섞을 수 없고, 오디오 레퍼런스에는 이미지나 영상 레퍼런스를 함께 넣습니다(영상 문서). 각 항목은 type과 url이고, 공개 HTTPS 링크나 data URI를 넣습니다. OmniaKey는 요청 전체를 Base64까지 포함해 1 MiB로 제한하므로(미디어 개요), 스크립트는 1024픽셀 JPEG를 보냅니다.
• 프롬프트는 input.prompt에 씁니다(영상 문서). 7,000자까지 들어갑니다(영상 가이드). 원하는 소리도 거기에 씁니다.

Python에서 Hailuo API를 호출하는 방법

Python 3와 requests가 필요하고, 키는 환경 변수에 넣습니다.

pip install requests
export OMNIAKEY_API_KEY="your-key"
python hailuo_h3.py t2v   # or i2v (needs bicycle.jpg) or r2v (needs robot.jpg)

인자는 t2v, i2v, r2v 세 가지뿐입니다. 이미지가 필요한 실행은 같은 폴더의 bicycle.jpg 또는 robot.jpg를 읽습니다.

실행한 스크립트는 아래와 같고, 한 글자도 바꾸지 않았습니다.

import base64
import os
import sys
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

DRUMMER = (
    "A street drummer plays a fast rhythm on upturned plastic buckets on a rainy city sidewalk "
    "at night. Neon signs reflect in the puddles and a few people with umbrellas walk past "
    "behind him. The camera slowly pushes in from a medium shot to a close-up of his hands and "
    "drumsticks. Realistic, handheld documentary look, with the sound of rain and drumming."
)
BICYCLE = (
    "A gentle breeze moves the daisies in the basket and a few petals drift down to the "
    "cobblestones. The camera slowly pushes in toward the basket. The bicycle and the wall "
    "stay exactly as they are."
)
ROBOT = (
    "The small orange robot from the reference image waters potted plants on a sunny "
    "apartment balcony with a red watering can. Medium shot, slow sideways camera move, "
    "city rooftops in the background."
)


def data_uri(path):
    # A local JPEG sent inline. The whole request must stay under 1 MiB, so keep it small.
    with open(path, "rb") as f:
        return "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()


def make_video(operation, prompt, parameters, media, out):
    task_input = {"prompt": prompt}
    if media:
        task_input["media"] = media

    # 1. Create the task. Reuse the same Idempotency-Key only when retrying this exact request.
    resp = requests.post(
        API,
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={
            "model": "minimax-h3",
            "type": "video",
            "operation": operation,
            "input": task_input,
            "parameters": parameters,
        },
        timeout=60,
    )
    resp.raise_for_status()
    task = resp.json()
    print(operation, "task:", task["id"])

    # 2. Poll the same task. Slow is not failed: never resubmit, keep polling this id.
    deadline = time.time() + 15 * 60
    while task["status"] in ("queued", "processing"):
        if time.time() > deadline:
            raise SystemExit(f"still {task['status']}: poll {task['id']} again later")
        time.sleep(5)
        task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] != "succeeded":
        raise SystemExit(f"{operation} ended {task['status']}: {task.get('error')}")

    # 3. Download the clip now: the signed URL lasts about an hour.
    asset = task["assets"][0]
    with open(out, "wb") as f:
        f.write(requests.get(asset["url"], timeout=120).content)
    print("saved", out, asset["byte_size"], "bytes")


mode = sys.argv[1] if len(sys.argv) > 1 else "t2v"
if mode == "t2v":
    make_video(
        "text_to_video", DRUMMER,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        None, "drummer.mp4",
    )
elif mode == "i2v":
    make_video(
        "image_to_video", BICYCLE,
        {"resolution": "768P", "duration": 5},
        [{"type": "first_frame", "url": data_uri("bicycle.jpg")}], "bicycle.mp4",
    )
elif mode == "r2v":
    make_video(
        "reference_to_video", ROBOT,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        [{"type": "reference_image", "url": data_uri("robot.jpg")}], "robot.mp4",
    )

2026년 10월 27일의 출력입니다.

$ python hailuo_h3.py t2v
text_to_video task: task_V5TXAJG7n3ny42imJNqgTXRL4L8PGStd
saved drummer.mp4 4612510 bytes
$ python hailuo_h3.py i2v
image_to_video task: task_c4m3wHmF79Cmq7ZhDrTnCyt8SmIaW1ls
saved bicycle.mp4 4705286 bytes
$ python hailuo_h3.py r2v
reference_to_video task: task_dqx1TYA7u0znN5PFTl9tbfdWgtbBUbKd
saved robot.mp4 5630121 bytes

세 번 모두 시작해서 저장까지 47초에서 60초가 걸렸습니다.

작업 id는 남겨 둡니다. 느린 작업은 실패가 아니므로 다시 제출하지 말고 같은 id를 계속 폴링합니다(미디어 개요). 서명된 다운로드 URL은 약 1시간, 작업 기록은 24시간 유지되므로 바로 저장하거나 다시 폴링해 새 URL을 받습니다. 다운로드 자체에는 API 키가 필요 없습니다.

세 모드에서 돌아온 결과

세 영상은 2026년 10월 26일 세 작업에서 나왔고, 요청 본문은 스크립트와 같습니다.

모든 영상은 MP4, H.264, 24 fps, 5.17초였고 32 kHz 스테레오 AAC 오디오가 들어 있었습니다. usage는 output_seconds: 5였습니다.

텍스트→영상: 거리 드러머

프롬프트는 스크립트의 DRUMMER입니다.

확인한 것:

• 밤의 젖은 보도에 빨강과 파랑 네온이 비치고, 주차된 차가 있고, 검은 후드 재킷을 입은 드러머가 엎어 놓은 파란 양동이 위로 몸을 숙이고 있습니다. 후드는 끝까지 얼굴을 가립니다.
• 카메라는 넓은 화면에서 손, 움직이는 스틱, 양동이 윗면 클로즈업으로 들어가고, 뒤로 우산을 쓴 사람이 지나갑니다.
• 네온 간판의 글자는 실제 단어가 아닙니다. 드럼 소리는 끝으로 갈수록 강해지지만 빗소리는 소리에서 뚜렷하지 않습니다.

고칠 점: 얼굴이 필요하면 "hood down, face visible"을 넣고, 빗소리가 들려야 하면 비 소리만 따로 한 문장으로 씁니다.

이미지→영상: 첫 프레임이 그대로

첫 프레임은 Nano Banana 2.1로 만든 정지 이미지이고, 프롬프트는 BICYCLE이며 움직임만 설명합니다.

확인한 것:

• 첫 프레임은 원본과 같습니다. 같은 빨간 자전거, 노란 회벽, 셔터, 화분, 조약돌이 있습니다.
• 카메라가 들어가 흰 데이지 바구니가 화면을 채우고, 자전거와 벽은 끝까지 모양을 지킵니다.
• 확인한 장면에서는 꽃잎이 떨어지는 것을 보지 못했습니다. 소리는 느린 피아노 독주인데, 프롬프트에는 소리도 음악도 쓰지 않았습니다.

고칠 점: 겉모습은 원본 이미지가 정하므로 움직임과 소리만 씁니다. 그리고 영상에 원하는 모양으로 정지 이미지를 만들어 둡니다.

레퍼런스→영상: 이미지 한 장이 캐릭터를 지킨다

레퍼런스는 Nano Banana 2.1로 만든 작은 주황색 로봇 이미지 한 장이고, 프롬프트는 ROBOT입니다.

확인한 것:

• 같은 로봇입니다. 주황색 둥근 몸, 둥근 파란 유리 눈, 끝에 공이 달린 짧은 안테나, 머리 옆 원반이 있고, 배경은 꽃과 허브 화분이 놓인 햇빛 드는 발코니입니다.
• 빨간 물조리개로 물을 붓고, 물줄기는 1초쯤부터 보이며, 카메라는 살짝 옆으로 흐릅니다.
• 소리는 흐르고 튀는 물소리이고 물줄기가 나타나기 직전에 시작하며, 음악은 없습니다.

고칠 점: 캐릭터는 고칠 것이 없었습니다. 여러 영상에서 같은 캐릭터를 유지하려면 매번 같은 레퍼런스 이미지를 씁니다.

소리: 직접 쓰거나 H3에 맡기기

프롬프트에 소리를 쓰지 않으면 H3가 골랐습니다. 로봇에는 물 주기에 맞는 물소리, 자전거에는 피아노입니다. 필요한 소리는 프롬프트에 씁니다. V2 생성 문서에는 소리를 끄는 스위치가 없으므로(생성 문서), 무음 영상이 필요하면 나중에 오디오 트랙을 뺍니다.

ffmpeg -i drummer.mp4 -an -c copy drummer-silent.mp4

이렇게 하면 H.264 영상만 남은 복사본이 만들어집니다. 길이는 5.17초 그대로이고 다시 인코딩하지 않습니다.

어떤 오류가 나오나요?

오류는 OmniaKey 작업 API에서, MiniMax를 직접 호출하면 MiniMax 쪽에서 돌아옵니다.

• 400 missing_idempotency_key: Idempotency-Key 헤더가 없음. 헤더 추가.
• 409 idempotency_key_reused: 같은 키에 다른 본문. 작업마다 새 키.
• 400 model_price_error: 1080P 또는 4K. 768P 또는 2K로 변경.
• 400 invalid_request: 본문이나 파라미터가 잘못됨. 파라미터 확인.
• 403 model_not_allowed: 키에 이 모델 권한이 없음. 키 권한 확인.
• 503 no_available_channel: 모델을 지금 쓸 수 없음. 나중에 재시도.
• provider_submit_uncertain: 제출 단계에서 거부됨. input.prompt를 쓰고 소재 확인.
• 작업 failed: 생성 실패. error 확인.

실패하거나 취소한 작업은 환불됩니다(미디어 개요). MiniMax API를 직접 호출하면 이렇습니다(오류 코드, 2026년 10월 26일 확인).

• MiniMax는 코드에 맞는 HTTP 상태도 함께 보냅니다. 예를 들어 1004에는 401, 2013에는 400입니다(생성 문서).
• V2의 H3는 분당 300 요청, 동시 30 작업까지 허용합니다(속도 제한).

Hailuo API 가격은 얼마인가요?

MiniMax는 H3를 출력 영상 초 단위로 과금하고, 단가는 모델과 해상도에 따라 다릅니다(가격 페이지, 2026년 10월 26일 확인).

이 단가로 768P 5초는 $0.40, 2K 10초는 $1.30, 2K 15초는 $1.95입니다.

• 입력 이미지는 작업당 처음 5장까지 무료(Max는 2장)이고, 그다음부터는 H3에서 장당 $0.04, 오디오 입력은 무료입니다. 입력 영상은 초 단위로 과금되고, Max에서는 입력 1초(768P에서 $0.143)가 출력 1초보다 비쌉니다. 같은 모델에 같은 해상도라면 세 작업 유형의 가격이 같습니다.
• H3는 사용한 만큼 내는 방식만 있고 MiniMax 영상 패키지에는 들어 있지 않습니다. Hailuo AI 앱 요금제의 초당 숫자는 앱 크레딧이지 API 가격이 아닙니다(앱).
• MiniMax 중국 플랫폼은 위안화 가격표를 따로 쓰므로 한쪽을 다른 쪽으로 환산하지 않습니다(중국 가격, 2026년 10월 26일 확인).
• OmniaKey에서는 영상 작업을 만들 때 출력 초만큼 과금하고, 실패하거나 취소한 작업은 환불합니다(미디어 개요).

OmniaKey의 현재 요금은 MiniMax H3 모델 페이지에, 요청 형식은 영상 API 문서에 있습니다.

자주 묻는 질문

Hailuo API는 무료인가요?

MiniMax 자체 API에서는 무료가 아닙니다. 가격, 빠른 시작, FAQ 페이지 어디에도 H3 무료 체험이나 크레딧이 없습니다(2026년 10월 26일 확인). 무료인 부분은 작업당 처음 5장의 입력 이미지와 오디오 입력뿐이고(가격), Hailuo AI 앱 크레딧은 API 크레딧으로 쓸 수 없습니다.

Hailuo 2.3과 MiniMax H3의 차이는 무엇인가요?

Hailuo 2.3은 V1에서 6초 또는 10초, 최대 1080P, 영상 한 편 단위 과금이고, MiniMax 정가는 768P 6초에 $0.28입니다(가격, V1 문서). H3는 V2에서 4초에서 15초, 768P 또는 2K, 초 단위 과금, 스테레오 소리를 씁니다(생성 문서, 모델 목록). 지금도 둘 다 제공됩니다(모델 FAQ).

MiniMax H3 Max는 무엇인가요?

MiniMax와 fal.ai가 함께 공개한 모델로, fal.ai가 속도를 위해 H3를 추가 학습했습니다(영상 가이드). 480P 또는 768P로 5초에서 15초 영상을 만들고, extra.prompt_expansion_mode는 disabled, balanced(기본값), quality를 받습니다(생성 문서). 레퍼런스를 받는지는 MiniMax 페이지마다 설명이 다릅니다. 영상 가이드와 모델 FAQ는 텍스트→영상, 이미지→영상만 적고, 생성 문서와 가격 페이지는 레퍼런스→영상도 적습니다.

MiniMax H3를 직접 실행할 수 있나요?

할 수 있습니다. 다만 지역 제한이 있습니다. 가중치는 Hugging Face(MiniMaxAI/MiniMax-H3)와 GitHub(MiniMax-AI/MiniMax-H3)에 있고, 라이선스는 MiniMax H3 Community License Agreement라는 자체 라이선스입니다(Hugging Face, GitHub). 2026년 8월 26일에 확인한 판에서는 미국, EU, 영국, 한국이 제외 지역이라 별도 라이선스가 필요합니다(로컬 배포 가이드).

업데이트 기록

2026년 10월 27일: 첫 버전. 영상은 2026년 10월 26일에 만들었습니다.